Avoid ast rewriting tool.polylith.build.top-namespace from discarding single-line comments or whitespaces

[yhkee0404]

Describe the bug
Setting top-namespace in [tool.polylith.build] of pyproject.toml discards single-line comments or whitespaces while rewriting the source files

To Reproduce
Steps to reproduce the behavior:

1. Open python-polylith-example-uv:
   https://github.com/DavidVujic/python-polylith-example-uv/blob/main/projects/consumer_project/pyproject.toml#L25
2. Run uv build --sdist projects/consumer_project/ && tar -xzvf dist/consumer_project-0.1.0.tar.gz -C stripped
3. Comment on top-namespace = "my_custom_ns" in the projects/consumer_project/pyproject.toml
4. (Optional) Add single-line comments starting with # or trivial whitespaces to components/example/kafka/consumer.py
5. Run uv build --sdist projects/consumer_project/ && tar -xzvf dist/consumer_project-0.1.0.tar.gz -C preserved
6. See the difference between stripped/consumer_project-0.1.0/my_custom_ns/example/kafka/consumer.py and preserved/consumer_project-0.1.0/example/kafka/consumer.py

Expected behavior
It should make no difference in source files other than prepending the new top-namespace to the previous single top-namespace in the import lines.

Desktop (please complete the following information):

• OS: Ubuntu 24.04.2 LTS
• Python version: cpython-3.12.11-linux-x86_64-gnu
• uv version: 0.7.12

Additional context

1. https://github.com/DavidVujic/python-polylith-docs/blob/c05923d459a46698c534484259787f363a436bdc/docs/deployment.md?plain=1#L140-L142

2. python-polylith/components/polylith/parsing/rewrite.py

   Line 70 in af30d4e

   def rewrite_modules(path: Path, ns: str, top_ns: str) -> List[str]:

3. Replacing ast with Instagram/LibCST could be helpful.

[DavidVujic]

Hi @yhkee0404, thank you for sharing this issue!

This is a limitation of the builtin Python AST parsing and unparsing feature. The output will result with the differences you mention: spaces, line breaks and comments.

There's third-party tools that does the AST parsing better than the builtin Python, but I have thought of it as a good-enough tradeoff. The rewrite is only needed and recommended for the use case when building several installable packages from a Polylith repo when users expect to install more than one of those packages (to avoid namespace collisions).

Additionally, I would recommend to only build wheels with this. I have thought of sdists as snapshots of the source code, but wheels as something "built" and packaged for a specific use case.

[DavidVujic]

I will transform this into a "discussion" and in the ideas section, for further investigation about using third-party AST/CST tooling. Thank you for sharing the link to the Instagram repo 🙏