New feature: view and validate brick interfaces

[DavidVujic]

Introducing a new feature: view and validate brick interfaces.

The feature is added to the poly deps --brick command.

Using a new option, --interface, will display the public interface of a specific brick. Also, it will highlight if there are any usages that bypasses the public interface. It is reported as information, and will not exit with a failed code. The motivation for this is that the Polylith tool will not stop you if it is valid Python. 😄

Example usage:

poly deps --brick my_brick --interface

Output:

used by   👈   my_brick   👉   uses           
────────────────────────────────────────────── 
the_other_brick                                      
another_brick                                           

With the addition:

my_brick exposes: 
function_one
function_two       

In case there are usages outside of the interface boundary:
a sub-module (in this example "hello_world") that isn't part of the public interface was used:

ℹ Found in the_other_brick: hello_world is not part of the public interface of my_brick. 

What's a brick interface?

The way the Polylith tool identifies a brick interface is by analyzing the contents of the __init__.py module. This feature will treat all imported things, all variables, classes and functions in the __init__.py module as part of the interface (unless marked as "private" using _). In addition, it will also check the contents of the __all__ variable if existing in the module.

This feature will make it possible to inspect how a brick is used across the Polylith workspace. With the notifications about usage outside of the interface boundaries, you will be able to identify any unexpected usages.

Future plans

Adding the interface validations as part of the poly check command, or introduce a new command. This is currently ongoing work.

Demo

In this recording, the message brick exposes functions via the __init__.py module. There's another module in the brick folder, called hello.py. When this is used from outside of the brick, it will be highlighted by the tool.

This example is using the Polylith CLI with uv, and it (of course) works the same way when using Poetry.