Description

Introducing a new feature: view and validate brick interfaces.

With this pull request, 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.

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. 

Motivation and Context

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.

How Has This Been Tested?

✅ CI
✅ Unit test
✅ local run of command, running against the Polylith repo itself

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)

Checklist:

• I have read the code of conduct.
• I have read the contributing guide.
• I have updated the documentation accordingly (if applicable).