Metadata-Version: 2.1
Name: poetry-multiproject-plugin
Version: 1.2.0
Summary: A Poetry plugin that makes it possible to use relative package includes.
Home-page: https://github.com/davidvujic/poetry-multiproject-plugin
Author: David Vujic
Requires-Python: >=3.8,<4.0
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Requires-Dist: mypy (>=0.991,<0.992)
Requires-Dist: poetry (>=1.2,<2.0)
Requires-Dist: tomlkit (>=0.11.5,<0.12.0)
Project-URL: Repository, https://github.com/davidvujic/poetry-multiproject-plugin
Description-Content-Type: text/markdown

# Poetry Multiproject Plugin

This is a Python `Poetry` plugin, adding the `build-project` and `check-project` commands.

[![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)

The `build-project` command will make it possible to use relative package includes.
This feature is very useful for monorepos and when sharing code between projects.

The `check-project` command is useful to check that dependencies are added properly in a project.
It uses the `MyPy` tool under the hood, and will output any errors from the static type checker.


## Use cases

### Microservices and apps
The 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.
The `build-project` command will collect the project-specific packages and build an installable artifact from it (i.e. a wheel or an sdist).

### Libraries?
Building libraries is also supported, but you will need to consider that the code will likely share the same top namespace with other libraries 
built 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.

Since Python libraries by default are installed in a "flat" folder structure, two libraries with the same top namespace will collide.

There 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).

## Usage
Navigate to the project folder (where the `pyproject.toml` file is).

Build a project:
``` shell
poetry build-project
```

Check the code used in a project:

``` shell
poetry check-project
```

Check the code, with a custom `MyPy` configuration to override the defaults:

``` shell
poetry check-project --config-file <PATH-TO-MYPY.INI-CONFIG-FILE>
```

### Usage for libraries
The `build-project` has a solution to the problem with top namespaces in libraries for __Python 3.9__ and more.
You can choose a custom namespace to be used in the build process, by using the `--with-top-namespace` flag. 

The 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.
The re-organizing and re-writing is performed on the relative includes.

The `build-project` command, with a custom top namespace:
```shell
poetry build-project --with-top-namespace my_namespace
```

#### The build output

Default behaviour of `build-project` (i.e. without any custom top namespace flag):
```shell
/my_package
   __init__.py
   my_module.py
```

By using the `--with-top-namespace` flag, the built artifact will look something like this:
```shell
my_namespace/
    /my_package
       __init__.py
       my_module.py
```

And will re-write the relevant module(s):

(before)
```python
from my_package import my_function
```

(after)
```python
from my_namespace.my_package import my_function
```

##### How is this done?
The code in this repo uses AST (Abstract Syntax Tree) parsing to modify source code.
The Python built-in `ast` module is used to parse and un-parse Python code.

## Installation
This plugin can be installed according to the official [Poetry docs](https://python-poetry.org/docs/plugins/#using-plugins).

``` shell
poetry self add poetry-multiproject-plugin
```

## What does it do?

the `poetry build-project` command will:

1. copy the actual project into a temporary folder.
2. collect relative includes - such as `include = "foo/bar", from = "../../shared"` -  and copy them into the temprary folder.
3. generate a new pyproject.toml.
4. run the `poetry build` command in the temporary folder.
5. copy the built `dist` folder (containing the wheel and sdist) into the actual project folder.
6. remove the temporary folder.


the `poetry check-project` command will:

1. copy the actual project into a temporary folder.
2. collect relative includes - such as `include = "foo/bar", from = "../../shared"` -  and copy them into the temprary folder.
3. generate a new pyproject.toml.
4. run `poetry install` in the temporary folder.
5. run `poetry run mypy` in the temporary folder.
6. remove the temporary folder.


The default setting for the underlying `MyPy` configuration is:

``` shell
--explicit-package-bases --namespace-packages --no-error-summary --no-color-output
```


## How is it different from the "poetry build" command?
Poetry does not allow package includes outside of the __project__ root.

``` shell
# Note the structure of the shared folder: namespace/package

packages = [
    { include = "my_namespace/my_package", from = "../../shared" }
    { include = "my_namespace/my_other_package", from = "../../shared" }
]
```

This plugin will allow relative package includes. You will now be able to share code between projects.

An suggested Monorepo structure, with the shared code extracted into a separate folder structure:

``` shell
projects/
  my_app/
    pyproject.toml (including a shared package)

  my_service/
    pyproject.toml (including other shared packages)

shared/
  my_namespace/
    my_package/
      __init__.py
      code.py

    my_other_package/
      __init__.py
      code.py
```

