{"id":17341067,"url":"https://github.com/davidvujic/poetry-multiproject-plugin","last_synced_at":"2025-04-05T06:05:57.821Z","repository":{"id":44604470,"uuid":"451124396","full_name":"DavidVujic/poetry-multiproject-plugin","owner":"DavidVujic","description":"A Poetry plugin that makes it simple to share code between projects in monorepos.","archived":false,"fork":false,"pushed_at":"2024-03-14T15:17:30.000Z","size":217,"stargazers_count":155,"open_issues_count":1,"forks_count":6,"subscribers_count":3,"default_branch":"main","last_synced_at":"2024-03-15T14:05:16.563Z","etag":null,"topics":["architecture","monorepo","poetry","poetry-plugin","polylith","python"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/poetry-multiproject-plugin/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/DavidVujic.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE-OF-CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-01-23T14:12:22.000Z","updated_at":"2024-06-25T20:18:26.236Z","dependencies_parsed_at":"2024-06-25T20:28:25.574Z","dependency_job_id":null,"html_url":"https://github.com/DavidVujic/poetry-multiproject-plugin","commit_stats":{"total_commits":49,"total_committers":2,"mean_commits":24.5,"dds":"0.020408163265306145","last_synced_commit":"23ba5895b72fd8f16219105599f9b53a133e7d48"},"previous_names":[],"tags_count":33,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DavidVujic%2Fpoetry-multiproject-plugin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DavidVujic%2Fpoetry-multiproject-plugin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DavidVujic%2Fpoetry-multiproject-plugin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DavidVujic%2Fpoetry-multiproject-plugin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/DavidVujic","download_url":"https://codeload.github.com/DavidVujic/poetry-multiproject-plugin/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247294537,"owners_count":20915340,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["architecture","monorepo","poetry","poetry-plugin","polylith","python"],"created_at":"2024-10-15T15:47:40.702Z","updated_at":"2025-04-05T06:05:57.804Z","avatar_url":"https://github.com/DavidVujic.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Poetry Multiproject Plugin\n\nThis is a Python `Poetry` plugin, adding the `build-project` and `check-project` commands.\n\n[![CircleCI](https://dl.circleci.com/status-badge/img/gh/DavidVujic/poetry-multiproject-plugin/tree/main.svg?style=svg)](https://dl.circleci.com/status-badge/redirect/gh/DavidVujic/poetry-multiproject-plugin/tree/main)\n\n[![CodeScene Code Health](https://codescene.io/projects/36629/status-badges/code-health)](https://codescene.io/projects/36629)\n\n[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=DavidVujic_poetry-multiproject-plugin\u0026metric=alert_status)](https://sonarcloud.io/summary/new_code?id=DavidVujic_poetry-multiproject-plugin)\n\n[![Download Stats](https://img.shields.io/pypi/dm/poetry-multiproject-plugin)](https://pypistats.org/packages/poetry-multiproject-plugin)\n\n\nThe `build-project` command will make it possible to use relative package includes.\nThis feature is very useful for monorepos and when sharing code between projects.\n\nThe `check-project` command is useful to check that dependencies are added properly in a project.\nIt uses the `MyPy` tool under the hood, and will output any errors from the static type checker.\n\n\n- [Use cases](#use-cases)\n- [Usage](#usage)\n- [Installation](#installation)\n- [What does it do?](#what-does-it-do)\n- [How is it different from the \"poetry build\" command?](#how-is-it-different-from-the-poetry-build-command)\n- [Organizing code](#organizing-code)\n\n## Use cases\n\n### Microservices and apps\nThe main use case is to support having one or more microservices or apps in a Monorepo, and share code between the services with namespaced packages.\nThe `build-project` command will collect the project-specific packages and build an installable artifact from it (i.e. a wheel or an sdist).\n\n### A basic building block for the Polylith Architecture\nThe Multiproject plugin makes it possible to organize Python projects according to the Polylith Architecture.\nThe plugin is the foundation for the __Python tools for the Polylith Architecture__ - also implemented as a __Poetry__ plugin.\n\nFor more about Polylith, have a look at the [Python-specific Polylith documentation](https://davidvujic.github.io/python-polylith-docs/).\n\n### Libraries?\nBuilding libraries is also supported, but you will need to consider that the code will likely share the same top namespace with other libraries \nbuilt from the same monorepo. It depends on your monorepo structure. This will likely be a problem when more than one of your libraries are installed into the same virtual environment.\n\nSince Python libraries by default are installed in a \"flat\" folder structure, two libraries with the same top namespace will collide.\n\nThere is a way to solve this issue, by using the `--with-top-namespace` flag of the `build-project` command. See [usage for libraries](#usage-for-libraries).\n\n## Usage\nNavigate to the project folder (where the `pyproject.toml` file is).\n\nBuild a project:\n``` shell\npoetry build-project\n```\n\nCheck the code used in a project:\n\n``` shell\npoetry check-project\n```\n\nCheck the code, with a custom `MyPy` configuration to override the defaults:\n\n``` shell\npoetry check-project --config-file \u003cPATH-TO-MYPY.INI-CONFIG-FILE\u003e\n```\n\n### Available command options\n\n#### Custom temp path\nA custom temporary path to use for reading, writing and deleting project content during the project build.\nThis option is useful for environments with restrictions on where scripts are allowed to store content.\n\nNOTE: The default temp path will be created as a sibling to the project to build, and is the recommended way in most cases.\n\n``` shell\npoetry build-project --custom-temp-path /tmp\npoetry check-project --custom-temp-path /tmp\n```\n\n\n### Usage for libraries\nThe `build-project` has a solution to the problem with top namespaces in libraries for __Python 3.9__ and more.\nYou can choose a custom namespace to be used in the build process, by using the `--with-top-namespace` flag. \n\nThe command will organize the namespaced packages according to the custom top namespace, and more importantly, re-write the imports made in the actual source code.\nThe re-organizing and re-writing is performed on the relative includes.\n\nThe `build-project` command, with a custom top namespace:\n```shell\npoetry build-project --with-top-namespace my_namespace\n```\n\n#### The build output\n\n###### Default(no flag)\n```shell\n/my_package\n   __init__.py\n   my_module.py\n```\n\n###### Namespace(`--with-top-namespace=my_namespace`)\n```shell\nmy_namespace/\n    /my_package\n       __init__.py\n       my_module.py\n```\n\n###### Namespace with path(`--with-top-namespace=my_namespace/subdir`)\n```shell\nmy_namespace/\n    /subdir\n        /my_package\n           __init__.py\n           my_module.py\n```\nAnd will re-write the relevant module(s):\n\n###### Default(no flag)\n```python\nfrom my_package import my_function\n```\n\n###### Namespace(`--with-top-namespace=my_namespace`)\n```python\nfrom my_namespace.my_package import my_function\n```\n\n###### Namespace with path(`--with-top-namespace=my_namespace/subdir`)\n```python\nfrom my_namespace.subdir.my_package import my_function\n```\n\n##### How is this done?\nThe code in this repo uses AST (Abstract Syntax Tree) parsing to modify source code.\nThe Python built-in `ast` module is used to parse and un-parse Python code.\n\n## Installation\nThis plugin can be installed according to the official [Poetry docs](https://python-poetry.org/docs/plugins/#using-plugins).\n\n``` shell\npoetry self add poetry-multiproject-plugin\n```\n\n## What does it do?\n\nthe `poetry build-project` command will:\n\n1. copy the actual project into a temporary folder.\n2. collect relative includes - such as `include = \"foo/bar\", from = \"../../shared\"` -  and copy them into the temprary folder.\n3. generate a new pyproject.toml.\n4. run the `poetry build` command in the temporary folder.\n5. copy the built `dist` folder (containing the wheel and sdist) into the actual project folder.\n6. remove the temporary folder.\n\n\nthe `poetry check-project` command will:\n\n1. copy the actual project into a temporary folder.\n2. collect relative includes - such as `include = \"foo/bar\", from = \"../../shared\"` -  and copy them into the temprary folder.\n3. generate a new pyproject.toml.\n4. run `poetry install` in the temporary folder.\n5. run `poetry run mypy` in the temporary folder.\n6. remove the temporary folder.\n\n\nThe default setting for the underlying `MyPy` configuration is:\n\n``` shell\n--explicit-package-bases --namespace-packages --no-error-summary --no-color-output\n```\n\n\n## How is it different from the \"poetry build\" command?\nPoetry does not allow package includes outside of the __project__ root.\n\n``` shell\n# Note the structure of the shared folder: namespace/package\n\npackages = [\n    { include = \"my_namespace/my_package\", from = \"../../shared\" }\n    { include = \"my_namespace/my_other_package\", from = \"../../shared\" }\n]\n```\n\nThis plugin will allow relative package includes. You will now be able to share code between projects.\n\n## Organizing code\nAn example Monorepo structure, having the shared code extracted into a separate folder structure:\n\n``` shell\nprojects/\n  my_app/\n    pyproject.toml (including selected shared packages)\n\n  my_service/\n    pyproject.toml (including selected shared packages)\n\nshared/\n  my_namespace/\n    my_package/\n      __init__.py\n      code.py\n\n    my_other_package/\n      __init__.py\n      code.py\n```\n\nA suggested structure, using [Polylith](https://davidvujic.github.io/python-polylith-docs/workspace/):\n\n``` shell\nworkspace/\n  bases/\n  components/\n  development/\n  projects/\n\n  poetry.lock\n\n  pyproject.toml\n  workspace.toml\n\n  README.md\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdavidvujic%2Fpoetry-multiproject-plugin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdavidvujic%2Fpoetry-multiproject-plugin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdavidvujic%2Fpoetry-multiproject-plugin/lists"}