tach-like reporting and enforcement of boundaries (tach check and tach report)

[gwdekker]

Hey David, back with some thoughts!

Are you aware of tach? We adopted it very early on in our monorepo as a great tool to help us define and document dependencies between components. the issue: tach is abandoned now by their makers. And to me it looks like that at least part of their functionality is very close to what the polylith tooling is already checking under the hood.

This issue serves to describe some of the core commands of tach (check and report) and to explore if there would be any interest to build this either into or on top of polylith-cli!

The basics of tach

The basic idea of tach the way we use it is that one defines a file called tach.toml which describes for each module which other modules it is allowed to import from. It by design limits itself to direct imports, not transitive imports.
Such a file does serve as a way of documenting the desired architecture patterns and make it very explicit which component imports from which other component.

A small example:

...
[[modules]]
path = "my_project.api_client"
depends_on = [
    "my_project.time_series_standards",
    "my_project.constants",
]
...

this is a snippet of our monorepo. It defines that the api_client component does depend on two other components, constants and time_series_standards. These two other components might depend on other components, but tach does not specify if they do.

tach check: enforce boundaries

The core command of tach is tach check. This does the following:

• it parses the full project to find all dependencies
• it compares it against the structure found in tach.toml
• it errors if there is a mismatch.

tach check Example 1

Suppose I did not add the constants module to the tach.toml file section above, but am importing from constants in the code of the api_client component. If I now run tach check I will get a detailed list of errors, specifying where in api_client I use a module that is not allowed:

Internal Dependencies
❌ components/my_project/api_client/api_client.py:13: Cannot use 'flint.constants.api_constants.DEVELOPMENT_API_HOST'. Module 'my_project.api_client' cannot depend on 'my_project.constants'.
...
❌ components/my_project/api_client/time_series_service_client.py:12: Cannot use 'my_project.constants.api_constants.TimeseriesServiceName'. Module 'my_project.api_client' cannot depend on 'my_project.constants'.

This is very useful in the following cases:

• Maybe I am importing something I shouldn't. tach check helps me to think twice. And it also makes it extremely easy for a code reviewer on an MR to see if somebody has added new coupling in the codebase - just check if tach.toml has been changed (tach check runs in CI so it is not possible to commit something where tach.toml does not reflect the state of the code base).
• I want to remove a certain dependency of component A on component B. I simply remove the dependency in tach.toml, then run tach check, and then go through the list of issues one by one.

tach check Example 2

suppose I define in tach.toml that I am allowed to import from a module called settings but in practice I do not. In such a case, if the tool is configured to strict, it will also report this as an error:

Unused Dependencies
❌ 'my_project.api_client' does not depend on: 
['my_project.settings']

Remove the unused dependencies from tach.toml, or 
consider running 'tach sync' to update module 
configuration and remove all unused dependencies.

tach report: report dependencies

Another very helpful command is tach report. It reports in detail which dependencies are detected in a specific module.

Output example below:

❯ tach report bases/my_project/bo_backtest
[ Dependency Report for 'bases/my_project/bo_backtest' ]
-------------------------------
[ Dependencies of 'bases/my_project/bo_backtest' ]
my_project/bo_backtest/__main__.py:1: Import 'my_project.arg_parse.types.register_argument_types'
my_project/bo_backtest/__main__.py:2: Import 'my_project.bo_backtest_core.run.run_backtest_flow'
my_project/bo_backtest/__main__.py:3: Import 'my_project.bo_backtest_core.settings_.BacktestRunTimeSettings'
my_project/bo_backtest/__main__.py:4: Import 'my_project.init.initialize_entrypoint'

-------------------------------
[ Usages of 'bases/my_project/bo_backtest' ]
No usages found.
-------------------------------

[ External Dependencies in 'bases/my_project/bo_backtest' ]
------------------------------------------------------
bases/my_project/bo_backtest/__local__.py:13: Import 'yaml' from package 'pyyaml'
bases/my_project/bo_backtest/__local__.py:17: Import 'jsonargparse.CLI' from package 'jsonargparse'

This is another very useful style of outputting a detailed report on the dependencies of a module. Running poly deps --brick bo_backtest gives me something similar in concept but different in output style:

❯ poly deps --brick bo_backtest      
                                                      
  used by   👈   bo_backtest   👉   uses              
 ──────────────────────────────────────────────────── 
                                    arg_parse         
                                    bo_backtest_core  
                                    init              
                                           

In some cases the poly deps output is enough already. I notice that in my repo, to look up that information, I default to searching in my tach.toml file to quickly get a similar result. The corresponding lines in tach.toml are:

[[modules]]
path = "my_project.bo_backtest"
depends_on = [
    "my_project.arg_parse",
    "my_project.bo_backtest_core",
    "my_project.init",
]

When I want more detailed info, I run the tach report command as mentioned above.

Other tach commands

There is more to tach, there are ideas around visualization, features around third party dependencies, selective test running (extremely useful and implemented slightly different (less opinionated and better imo) than poly test), etc. but that is for now beyond the scope of this post. The core functionality is what I described above: the tach check command, which takes the tach.toml file and compares it against the actual structure as observed from the code/the AST.

Summary and ideas forward

Long story short: I see clear overlaps between what the poly tooling is already doing, and the functionality in tach that I love and use on a daily basis - but tach is abandoned. If I want to get rid of tach and leverage the existing work done in poly, I see several potential ways forward, in increasing degrees of collaboration - all depending on whether you feel this is interesting or in scope at all, and have the time and interest to invest in this:

1. I build stuff around poly, similar to what I did here, building on non-public API parts of polylith
2. I fork python-polylith and work from there
3. We try to define a python SDK or more programmatic interface to use polylith more flexibly - using the core functionality but having more freedom to build specific things on top. In that scenario, I could try to build the tach-like setup as a layer on top of python-polylith and maybe publish it open source.
4. The core functionlaity of tach gets fully absorbed into poly.

Very curious to hear what you think!

[DavidVujic]

This is very useful for me to know what to develop further on, thank you! I wasn't aware of tach being abandoned, and have thought of the features there as something teams could use in addition to what the Polylith tooling offers. I'll read your post more carefully later this week, to identify what the low hanging fruits might be.

[DavidVujic]

Adding some notes here as I read your summary:

tach check and poly check seems very similar (but I haven't read up on the details on tach yet).
With the latest additions to the poly check command does checks on

• any missing brick dependencies (with a fail exit code)
• unused brick dependencies (no failed exit code, only information) announced in 🎉 New feature: the poly check command will show unused bricks in projects #361
• missing third-party dependencies/libraries (fail with exit code)

I have thought of adding data about "interfaces", in a similar way as with the Clojure version of the poly tool. The way I see "interface" in Python and for Polylith bricks would be the __init__.py. I think that is the one that would be the "pythonic" option instead of introducing a interface.py or a TOML configuration. I see a possibility for it to be used for a strict brick interface check.

The tach report looks very much like an equivalent to poly info, but where Polylith views the world from a brick point of view. The poly info command has potential to include a lot more details, just like the Clojure version (if there's interfaces and tests etc. for a brick). The poly deps probably also is overlapping the tach report.

[gwdekker]

Yes, I also think that the core functionality is very similar. We have both tools running in parallel in our monorepo and have had it like that for a long time now (over a year i think). Here is where I see the differences in practice, from experience working with both tools in parallel:

Having an explicit file checked in with the structure is very helpful

The core of tach is that you have a tach.toml which defines how all modules (bricks in our case) depend on each other. This proves to be extremely useful to have:

• you have it checked in as part of your repo, so you can immediately see which modules depend on each other.
• you can easily build additional rules on top by parsing that tach.toml file and do sanity checks, enforce naming rules, etc. It opens up for a lot of flexibility.
• If you have a larger merge request by a colleague, one of the things I always want to check for is whether they made the code more coupled. This is super simple now: if there is a change in tach.toml something changed, if not, then we are good.
• in refactoring the structure of the monorepo to reduce coupling, it has been a great help to browse through tach.toml to just grasp the dependencies.

It seems to me that poly deps provides very similar output, the main difference in design here I think is the choice to then store this in a file or not.

Poly check vs tach check

If I understand poly check correctly, especially with the --verbose output it seems to be very similar to tach check indeed. The main and core difference is that poly check compares the resulting found dependency structure against what is allowed as defined in tach.toml. This is for me the crucial piece that tach offers that poly check doesn't for now. In addition there is tach sync which adds the found new dependencies to tach.toml - but this I think would be trivial to add and is more of a convenience helper than anything really new.

verbosity/clarity of outputs

I find in general the tach versions of the commands to be more actionable, as it often points me directly to the line or the dependency I am supposed to fix/change. With tach this is sometimes a bit of a struggle. One minor but very helpful improvement would be if the error messages would report if the error concerns a base, a component or a project - as in practice this is not always cllear from the name. Also having more details re line numbers, files etc could be an improvement - but it is also a style choice of course - what is helpful for one would be considered clutter/noise for somebody else.

While typing this out, it becomes again clear to me that it's really about how to use/consume the output of the dependency structure analysis rather than any missing functionality in either of the tools.

Hope this helps!

[DavidVujic]

I especially like the thing with the "before-after" about coupling! Something similar could be added in the poly diff command - a more detailed view, per brick, where you can see something similar to the poly deps --brick, but with the changes highlighted.

[DavidVujic]

The poly command(s) could potentially also persist the current state in versioned files. I think that would be possible today also, with some custom scripting (pipe output to file). But could be a nice addition to the poly tool too.

[gwdekker]

Yes I would love it! If we would persist the current state, would the next step then be to do what tach does and have a command that validates that that state is still current? (that is what tach check does).

Let me know if there is anything here I could help with - i would be interested in spending some time contributing to this work if you are interested.

[DavidVujic]

I released a new version with support for saving the output to file: #373

I hope this will be useful!