Docs: clarify how to proceed after setup steps

[maxalbert]

Hi @DavidVujic, first of all huge thanks for introducing the Polylith architecture to the Python community and for your invaluable work on the related tooling.

Describe the bug

I recently discovered the Polylith architecture and read up about its concepts in the Clojure-focused GitBook and in your Python-focused documentation.

I wanted to try it out with a hands-on example and followed the steps in the Setup section (using uv) to create a minimal Polylith workspace.

However, I struggled to get the development workflow going in the way I expected. I'm unsure if my expectations were wrong or if some crucial steps are missing in the setup documentation to get to a fully functioning development project.

To Reproduce

Note: for reference, a repo with the workspace structure resulting from the steps below is available here.

Start in an empty directory and make sure that python and uv are available. I'm using the following versions:

$ python --version
Python 3.13.0

$ uv --version
uv 0.4.30

Then follow the steps in the setup guide:

$ uv init --name=polylith-bug-report
$ uv add --dev polylith-cli
$ uv add --dev ipython  # optional, for convenience

$ uv run poly create workspace --name bug_report --theme loose

Now edit pyproject.toml according to the instructions here by adding the following sections:

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[tool.hatch.build]
dev-mode-dirs = ["components", "bases", "development", "."]

Finally, run:

$ uv sync

Expected behavior

At this stage, I expected to be able to enter a Python console and import the bug_report module. However:

$ python -c "import bug_report"

Traceback (most recent call last):
  File "<string>", line 1, in <module>
    import bug_report
ModuleNotFoundError: No module named 'bug_report'

It turns out that if I create a new component then the import does work:

$ uv run poly create component --name dummy

$ python -c "import bug_report; print(bug_report is not None)"
True

However, this is quite nonintuitive. It actually took me quite a few attempts of debugging and experimenting with different things to realise that this was all that's needed.

I'm still not sure if I'm missing any further setup steps, for example in order to get the development project fully set up and working. I have included a couple of my open questions below.

Desktop (please complete the following information):

• OS: Mac OS 10.14.6
• Python version: 3.13.0
• Uv version: 0.4.30

Additional context / Further questions

As indicated above, I'm not sure whether completing the setup steps is sufficient for a fully working Polylith workspace. Open questions:

1. The docs section on Projects & pyproject.toml mentions that the project-specific pyproject.toml files need hatch-polylith-bricks as an additional build system dependency, and also require the section [tool.hatch.build.hooks.polylith-bricks] to be present (even if it is empty). Is this also necessary to set up the development project in the toplevel pyproject.toml file?

2. Do I need to run poly sync to complete the workspace setup? If I do this (after creating the dummy component above), the following section is added to the toplevel pyproject.toml file:

   [tool.polylith.bricks]
    "components/bug_report/dummy" = "bug_report/dummy"

   However, I think that I can import new components (and presumably bases, although I haven't tried this) without this section being present. Does it make a difference?

Many thanks for reading and any clarifications!

[DavidVujic]

Hi @maxalbert, thank you for the detailed report! ⭐

I think that the bug_report import fails because there isn't any source code added into the environment at that point. I think that it will be the same issue in a non-polylith scenario. It would explain why the importing works after creating a component: when python code is added into the repo. Note that you will need to have an activated virtual environment, or running the command within a uv run context.

I should probably clarify this part in the docs.

The open questions:

1. no, the development pyproject.toml should not contain the Hatch build hook. The Build hook is for packaging individual projects (building wheels).
2. Running poly sync is optional, and it will add any missing components or bases to the development project. It will also add missing components to the projects, if there is a base importing it.

[DavidVujic]

I have added a new sub-section called Next stepsin the Setup section of the docs, that I hope clarifies the install and setup flow: https://davidvujic.github.io/python-polylith-docs/setup/#next-steps

[DavidVujic]

(I will move this to Discussions and Q&A)

[maxalbert]

@DavidVujic Many thanks for the swift response and for adding this docs section. IMHO it really makes the setup process a lot clearer. Much appreciated.

I have a tangentially related question (which I'm happy to ask in a separate thread if more appropriate). While going through the setup docs and trying to better understand how everything works together, I was trying to import different components etc. from within an interactive IPython console. Unfortunately, due to the use of namespace packages the tab completion was quite limited, which made the exploration more cumbersome than I had hoped. Can you think of any ways to improve this? A quick web search for didn't result in any obvious ways to add tab completion for namespace packages, but I was wondering if it was possible to dynamically add support via some plugin or build hook (for example by dynamically creating a __dir__() method on the namespace package)? This may not be feasible, but I was curious if you have any thoughts.

[DavidVujic]

Oh, I wasn't aware of any limitations with namespace packages. When trying out in the REPL with IPython, I get tab completion. The help() function and the __doc__ works as expected. Mabye there is something else missing?

The REPL should work very well with this setup (it's one of the design goals of Polylith to have have a really good Developer Experience). There's also the dedicated development folder, where you can experiment with code in your IDE. I usually have a david.py module where I import and try out code (it's kind of like the "scratch files" feature of PyCharm, but with git versioning).

Here's a short recording of the autocomplete. Please let me know if I have misunderstood what you mean!