# PYMSDL_Template
***PYMSDL<sup>(PYthon Maven Standard Directory Layout)</sup> template*** is a
Python [Poetry](https://python-poetry.org/) template inspired from
the [Maven Standard Directory Layout](https://maven.apache.org/guides/introduction/introduction-to-the-standard-directory-layout.html)
.
[](https://github.com/dev4py/pymsdl_template/actions/workflows/ci.yml) <br/>
[](https://github.com/dev4py/pymsdl_template/actions/workflows/on_release.yml) <br/>
[](https://github.com/dev4py/pymsdl_template/actions/workflows/weekly_checks.yml) <br/>
[](https://www.python.org/) <br/>
[](https://python-poetry.org/) <br/>
[](https://github.com/St4rG00se) <br/>
 <br/>
[](https://opensource.org/licenses/Apache-2.0)
**<img src="https://upload.wikimedia.org/wikipedia/commons/thumb/1/17/Warning.svg/25px-Warning.svg.png" alt="warning-icon" width="20px" height="20px"/>
WARNING Prerequisites:**
* `Python >= 3.10.1`
* `Poetry >= 1.1.0`
***Since there are some existing limitations, it is strongly advised to read
the [Project organization](#project-organization) part before the [Project commands](#project-commands) one.***
> ***Note:** this template is configured in order to work with [Poetry](https://python-poetry.org/).*
>
> *if you want to use another layout than [Maven Standard Directory Layout](https://maven.apache.org/guides/introduction/introduction-to-the-standard-directory-layout.html),
> you can change the **project structure** as explained in the
> [pyproject.toml & project.py files](#pyprojecttoml--projectpy-files) part.*
## Table of contents
* [Quickstart](#quickstart)
+ [Create a new project](#create-a-new-project)
- [1. Click on Use this template](#1-click-on-use-this-template)
- [2. Fork this template](#2-fork-this-template)
- [3. Clone/download this template](#3-clonedownload-this-template)
+ [Prepare your environment](#prepare-your-environment)
+ [Test your setup](#test-your-setup)
+ [Manage your project](#manage-your-project)
+ [Let's dev](#lets-dev)
* [Project organization](#project-organization)
+ [pyproject.toml & project.py files](#pyprojecttoml--projectpy-files)
+ [Maven Standard Directory Layout with python](#maven-standard-directory-layout-with-python)
- [Sources & Resources directories configuration](#sources--resources-directories-configuration)
- [<span style='color: orange'><img src="https://upload.wikimedia.org/wikipedia/commons/thumb/1/17/Warning.svg/25px-Warning.svg.png" alt="warning-icon" width="20px" height="20px"/> WARNING: Limitations</span>](#-warning-limitations)
* [A. Use root package names with suffix](#a-use-root-package-names-with-suffix)
* [B. Use namespace package as root package](#b-use-namespace-package-as-root-package)
* [C. Don't fully respect the Maven Standard Directory Layout](#c-dont-fully-respect-the-maven-standard-directory-layout)
* [Project commands](#project-commands)
+ [Clean project](#clean-project)
+ [Run module](#run-module)
+ [Run tox](#run-tox)
+ [Run linter](#run-linter)
+ [Run tests](#run-tests)
+ [Run type check](#run-type-check)
+ [Run mutation](#run-mutation)
+ [Build](#build)
- [Wheel archive](#wheel-archive)
- [Source Distribution](#source-distribution-archive)
+ [Delivery *(on https://pypi.org/)*](#delivery-on-httpspypiorg)
* [Docker](#docker)
+ [Dev environment](#dev-environment)
- [Build the pymsdl:devenv docker image](#build-the-pymsdldevenv-docker-image)
- [Run the pymsdl:devenv environment](#run-the-pymsdldevenv-environment)
+ [Docker application image delivery](#docker-application-image-delivery)
- [Build your docker image](#build-your-docker-image)
- [Run your docker image](#run-your-docker-image)
- [Push your docker image](#push-your-docker-image)
* [Workflows](#workflows)
+ [CI](#ci)
+ [On_release](#on_release)
+ [Weekly_checks](#weekly_checks)
## Quickstart
### Create a new project
There are several ways to use this template for your project:
#### 1. Click on [Use this template](https://github.com/dev4py/pymsdl_template/generate)
Create a new project from the [Use this template](https://github.com/dev4py/pymsdl_template/generate) button is the
standard way for a new GitHub project from a template.
See: [Creating a repository from a template](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-repository-from-a-template)
> ***Note:** You have to be logged in*
#### 2. Fork this template
Create a new project by forking the template is the "old way" to work with templates on GitHub.
However, there are some differences between "fork" and "use template"
explained [here](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-repository-from-a-template)
which can help you about your choice.
See: [About forks](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/about-forks)
#### 3. Clone/download this template
This is a way to use if you are creating a new project but, you are not working on GitHub.
### Prepare your environment
PYMSDL template requires `Python >= 3.10.1` and `Poetry >= 1.1.0`.
**If your environment is not ready yet, a docker ready to work environment is provided
(see [Dev environment](#dev-environment)).**
In order to simplify your pipeline evolution and local use, this template provides you a python script with basic
management commands. See: [Project commands](#project-commands).
You have to run this command line in order to download your project dependencies:
> ```sh
> ./project.py load_deps
> ```
### Test your setup
PYMSDL template provides a simple sample project named `hellopymsdl`. You can test your setup by running this command
line:
> ```sh
> ./project.py test
> ```
### Manage your project
Since this template use [Poetry](https://python-poetry.org/) you have to learn each
[poetry command](https://python-poetry.org/docs/cli/).
Moreover, this template provides you a python script with basic management commands.
See: [Project commands](#project-commands)
> ***Note** [Project commands](#project-commands) samples should work on the provided `hellopymsdl` simple sample
> project.*
### Let's dev
Once previous steps are done you can start your developments by respecting the content
of [Project organization](#project-organization) part.
## Project organization
### pyproject.toml & project.py files
The [pyproject.toml](./pyproject.toml) file is used in order to describe and deliver correctly your project.
See:
* [PEP 517 – A build-system independent format for source trees](https://www.python.org/dev/peps/pep-0517/)
* [PEP 518 – Specifying Minimum Build System Requirements for Python Projects](https://www.python.org/dev/peps/pep-0518/)
* [PEP 621 – Storing project metadata in pyproject.toml](https://www.python.org/dev/peps/pep-0621/)
* [PEP 660 – Editable installs for pyproject.toml based builds (wheel based)](https://www.python.org/dev/peps/pep-0660/)
* [Poetry pyproject.toml details](https://python-poetry.org/docs/pyproject/)
Moreover, this template provides the [project.py](./project.py) file which is a command line wrapper in order to
simplify the project evolution (see [Project commands](#project-commands)).
When you start a new project from this template, ***YOU DON'T HAVE TO UPDATE THE [PROJECT.PY](./project.py) FILE***,
until you switch from [Poetry](https://python-poetry.org/) to another tool.
In order to set your project properties, you just have to update the [pyproject.toml](./pyproject.toml).
> **Note:** If you don't want to use the [Maven Standard Directory Layout](https://maven.apache.org/guides/introduction/introduction-to-the-standard-directory-layout.html),
> you can reconfigure the project structure by replacing each `/src/main/...` or `/src/test/...` by your structure in
> the [pyproject.toml](./pyproject.toml) file.
### Maven Standard Directory Layout with python
#### Sources & Resources directories configuration
This template attempts to reach
the [Maven Standard Directory Layout](https://maven.apache.org/guides/introduction/introduction-to-the-standard-directory-layout.html)
for python.
That's why you will find the following directory structure:
* ***src/main/python:*** Should contains your application sources
* ***src/main/resources:*** Should contains your application resources
* ***src/test/python:*** Should contains your application **test** sources
* ***src/test/resources:*** Should contains your application **test** resources
**Sources** and **resources** directories must be in
your **[PYTHONPATH](https://docs.python.org/3/using/cmdline.html#envvar-PYTHONPATH).**
**However, if you don't want to configure your PYTHONPATH, you can use the provided [Run module](#run-module) command.**
> ***Note:** if you are using IDE like **[<img src="https://upload.wikimedia.org/wikipedia/commons/1/1d/PyCharm_Icon.svg" alt="Pycharm-icon" width="17px" height="17px"/>
Pycharm](https://www.jetbrains.com/pycharm/)**
> , it means `src/main/python` and `src/main/resources` must be marked as **Sources Root**
> `(Right click on these directories > Mark directory as > Sources Root)`
> and `src/test/python` and `src/test/resources` must be marked as **Test Sources Root**
> `(Right click on these directories > Mark directory as > Test Sources Root)`.*
> ***Note:** Due to a [Poetry](https://python-poetry.org/) limitation, using installation with edit mode
> (`pip install -e .`) in order to avoid the
> [PYTHONPATH](https://docs.python.org/3/using/cmdline.html#envvar-PYTHONPATH) configuration will not work and fail
> with:*
>
> `build backend is missing the 'build_editable' ... Consider using a build backend that supports PEP 660.`
#### <span style='color: orange'><img src="https://upload.wikimedia.org/wikipedia/commons/thumb/1/17/Warning.svg/25px-Warning.svg.png" alt="warning-icon" width="20px" height="20px"/> WARNING: Limitations</span>
Python resources MUST be located in a python package (i.e.: directory containing an `__init__.py` file). (You can see
that like a java classpath.)
Since a package sources cannot be split in several directories, each package in `src/main/python`,
`src/main/resources`, `src/test/python` and `src/test/resources` directories must be different. In case of conflict, the
package from the first directory found in
your **[PYTHONPATH](https://docs.python.org/3/using/cmdline.html#envvar-PYTHONPATH)** will be used.
So if you want to respect the
*[Maven Standard Directory Layout](https://maven.apache.org/guides/introduction/introduction-to-the-standard-directory-layout.html)*
there are several suggestions:
##### A. Use root package names with suffix
Use root package names with suffixes like this:
* *<My_Root_Package_Name>* for sources (in `src/main/python`)
* *<My_Root_Package_Name>`_rsrc`* for resources (in `src/main/resources`)
* *<My_Root_Package_Name>`_test`* for test sources (in `src/test/python`)
* *<My_Root_Package_Name>`_test_rsrc`* for test resources (in `src/test/resources`)
> **Project structure example:**
>
> ```sh
> <My_Project>
> |- ...
> |- src
> |- main
> | |- python
> | | |- <MY_ROOT_PACKAGE_NAME>
> | | |- __init__.py
> | | |- ...
> | |- resources
> | |- <MY_ROOT_PACKAGE_NAME>_rsrc
> | |- __init__.py
> | |- ...
> |- test
> |- python
> | |- <MY_ROOT_PACKAGE_NAME>_test
> | |- __init__.py
> | |- ...
> |- resources
> |- <MY_ROOT_PACKAGE_NAME>_test_rsrc
> |- __init__.py
> |- ...
> ```
> ***Note:** since root package names are different (`_rsrc`, `_test`, `_test_rsrc` suffixes) it cannot exist conflict
> between packages in `src/main/python`, `src/main/resources`, `src/test/python` and `src/test/resources`.*
> ***Note:** `_rsrc`, `_test`, `_test_rsrc` are just suggested suffixes you can use your own suffixes.*
##### B. Use namespace package as root package
If you really want a common root package name, you can use a `namespace package` as root. This `namespace package` must
contain packages without conflict between sources and resources directories.
> *Reminder: A namespace package doesn't contain any source or `__init__.py` file.*
> **Project structure with namespace package as root package example:**
>
> ```sh
> <My_Project>
> |- ...
> |- src
> |- main
> | |- python
> | | |- <MY_ROOT_NAMESPACE_PACKAGE_NAME>
> | | |- <MY_PACKAGE_NAME>
> | | | |- __init__.py
> | | | |- ...
> | | |- ...
> | |- resources
> | |- <MY_ROOT_NAMESPACE_PACKAGE_NAME>
> | |- <MY_PACKAGE_NAME>_rsrc
> | | |- __init__.py
> | | |- ...
> | |- ...
> |- test
> |- python
> | |- <MY_ROOT_NAMESPACE_PACKAGE_NAME>
> | |- <MY_PACKAGE_NAME>_test
> | | |- __init__.py
> | | |- ...
> | |- ...
> |- resources
> |- <MY_ROOT_NAMESPACE_PACKAGE_NAME>
> |- <MY_PACKAGE_NAME>_test_rsrc
> | |- __init__.py
> | |- ...
> |- ...
> ```
##### C. Don't fully respect the Maven Standard Directory Layout
If you are not agree with the previous suggestions, you can remove the `src/main/resources`, `src/test/python`
and `src/test/resources` directories and put your resources and tests directly into the `src/main/python` directory.
> **Note:** if you do that, your tests will be included during your project/package installation (not only in the source
> distribution as it is suggested in the best practices).
## Project commands
Project commands are available from the [project.py](./project.py) python file.
If you take a look at this file, you will see that it contains:
* **A shared `project_properties` variable** which contains all project properties.
* **A command line wrapper:** this wrapper is designed in order to be used locally and in your deployment scripts (like
CI/CD).
Indeed, by using it, if you want to update you "project tools" (sample: switching from poetry to setuptools) you just
have to update this script but not all your pipeline.
Moreover, this wrapper manage the project [PYTHONPATH](https://docs.python.org/3/using/cmdline.html#envvar-PYTHONPATH)
for you.
> **Command wrapper man:**
> ```sh
> PROJECT COMMANDS WRAPPER:
>
> Usage: python project.py <COMMAND_1> <arg1_1 ...> ... <COMMAND_N> <argN_1 ...>
> Note: In order to get the wrapped command help, you can try python project.py <command> --help
>
> Available commands are:
> load_deps Install all dependencies (dev included)
> clean Remove directories generated by the "build" commands (like 'sdist' or 'wheel')
> run Run module which can be in the project structure without having to configure the PYTHONPATH
> tox Run tox
> lint Run linter
> test Run configured unit tests
> typing Run typing checker
> mut Run mutation tests
> wheel Build Wheel archive
> sdist Build sdist archive
> upload Upload available deliveries
> ```
> ***Note:** Using `--help` argument on a command or if an error occurs, the message will be from the wrapped command
> line.*
### Load dependencies
> ```sh
> ./project.py load_deps
> ```
or
> ```sh
> python project.py load_deps
> ```
### Clean project
> ```sh
> ./project.py clean
> ```
or
> ```sh
> python project.py clean
> ```
> ***Note:** Remove dist directory and test cache directories.*
### Run module
PYMSDL template provides you a run python module command line (even in the **project packages**) without having to
configure your **[PYTHONPATH](https://docs.python.org/3/using/cmdline.html#envvar-PYTHONPATH)**:
> ```sh
> ./project.py run -m <MODULE_NAME>
> ```
or
> ```sh
> python project.py run -m <MODULE_NAME>
> ```
> ***Note:** the `run` command is like opening python in your poetry virtual environment and the project structure
> configured in your **[PYTHONPATH](https://docs.python.org/3/using/cmdline.html#envvar-PYTHONPATH).***
>
> *Moreover, your opened `python` will work from the current directory (not from the `project.py` one).*
> **Examples:**
>
> **- Open a *python console* from the current directory:**
> ```
> ./project.py run
> ```
> ***Note:** `<PATH_TO_PROJECT.PY> run` will open a python console in your current directory not in the `project.py`
> one.*
>
> **- Run *module* example:**
> ```sh
> ./project.py run -m hellopymsdl.__main__
> ```
> Run the `__main__.py` module from `hellopymsdl` package.
>
> **- Run *package* example:**
> ```sh
> ./project.py run -m hellopymsdl
> ````
> ***Note:** your package MUST contains a `__main__.py` module.*
>
> **- Run *module* from path example:**
> ```sh
> ./project.py run src/main/python/hellopymsdl/__main__.py
> ```
> Run the `__main__.py` module from `hellopymsdl` package.
> **WARNING: the path is from the command `CWD` if not absolute.**
>
> **- Run *package* from path example:**
> ```sh
> ./project.py run src/main/python/hellopymsdl
> ```
> ***Note:** your package MUST contains a `__main__.py` module.*
> **WARNING: the path is from the command `CWD` if not absolute.**
>
> **- Run *module* with arguments example (using --args string parameter):**
> ```sh
> ./project.py run -m hellopymsdl.__main__ --arg1 --arg2=my_arg2 ...
> ```
### Run tox
PYMSDL template uses [tox](https://tox.wiki/) in order to manage your tests (unit tests, lint, etc.)
> ```sh
> ./project.py tox
> ```
or
> ```sh
> python project.py tox
> ```
> ***Note:** You will find the [tox](https://tox.wiki/) configuration in the [pyproject.toml](./pyproject.toml) file
> (`[tool.tox]` section).*
>
> The default [tox](https://tox.wiki/) configuration provides the following `envlist`:
>
>* ***pylint:*** Executes the configured linter
>* ***covclean:*** Cleans the coverage reports
>* ***py310:*** Executes the configured test runner under python 3.10
>* ***report:*** Generates console, html and xml reports
>* ***mutation:*** Executes mutation testing and generate reports
>
> Moreover, the provided configuration runs each test on INSTALLED packages (Not on the given sources even if obviously
> the installed packages depends on the given sources). The goal is to test definitive installed versions.
### Run linter
> ```sh
> ./project.py lint
> ```
or
> ```sh
> python project.py lint
> ```
> ***Note:** `json` and `txt` reports will be available in `build/reports/lint`.*
> ***Note:** By default this template uses [pylint](https://pylint.org/) as linter. You will find the linter
> configuration in the [pyproject.toml](./pyproject.toml) file (`[tool.pylint....]` sections).*
> ***Note:** This command uses [tox](#run-tox) but only in order to call the linter.*
### Run tests
This project is configured to execute tests with [**Pytest**](https://docs.pytest.org/):
> ```sh
> ./project.py test
> ```
or
> ```sh
> python project.py test
> ```
> ***Note:** `html`, `json` and `xml` reports will be available in `build/reports/coverage`.*
> ***Note:** If you change the project structure, don't forget to update the `[tool.pytest.ini_options]` section from
> the [pyproject.toml](./pyproject.toml) file.*
> ***Note:** This command uses [tox](#run-tox) but only in order to run your tests.*
### Run type check
PYMSDL template provides a static type checker by using [**mypy**](http://mypy-lang.org/).
See:
* [PEP 484 – Type Hints](https://peps.python.org/pep-0484/)
* [PEP 526 – Syntax for Variable Annotations](https://peps.python.org/pep-0526/)
> ```sh
> ./project.py typing
> ```
or
> ```sh
> python project.py typing
> ```
> ***Note:** Reports will be available in `build/reports/typing`.*
> ***Note:** If you change the project structure, don't forget to update the [pyproject.toml](./pyproject.toml) file
> (`[tool.tox]` and `[tool.mypy]` sections).*
> ***Note:** This command uses [tox](#run-tox) but only in order to call the type checker (by default: `mypy`).*
### Run mutation
This template provides mutation testing by using [**mutmut**](https://mutmut.readthedocs.io/en/latest/):
> ```sh
> ./project.py mut
> ```
or
> ```sh
> python project.py mut
> ```
> ***Note:** `html` report will be available in `build/reports/mutation`.*
> ***Note:** If you change the project structure, don't forget to update the [pyproject.toml](./pyproject.toml) file.*
> ***Note:** This command uses [tox](#run-tox) but only in order to run your tests.*
### Build
#### Wheel archive
> ```sh
> ./project.py wheel
> ```
or
> ```sh
> python project.py wheel
> ```
#### Source Distribution archive
If you need a source distribution (sdist) archive:
> ```sh
> ./project.py sdist
> ```
or
> ```sh
> python project.py sdist
> ```
### Delivery *(on https://pypi.org/)*
> ```sh
> ./project.py upload
> ```
or
> ```sh
> python project.py upload
> ```
> ***Note:** Obviously, this command must be executed after the [Build](#build) one.*
## Docker
**<img src="https://upload.wikimedia.org/wikipedia/commons/thumb/1/17/Warning.svg/25px-Warning.svg.png" alt="warning-icon" width="20px" height="20px"/>
WARNING This part requires [docker](https://www.docker.com/) to be installed**
### Dev environment
If you haven't a python/poetry environment installed, PYMSDL template provides you a "ready to work" Dockerfile:
#### Build the pymsdl:devenv docker image
> ```sh
> docker build -t pymsdl:devenv-1.0.0 -f docker/devenv/Dockerfile .
> ```
#### Run the pymsdl:devenv environment
> ```sh
> docker run --rm -it --name pymsdl-dev-env -v ${PWD}:/app pymsdl:devenv-1.0.0
> ```
It opens a `sh` on a well configured python/poetry environment.
> ***Note:** you have to use the volume (`-v`) option in order to mount your project files into the container `/app`
> directory. This is useful for staying up to date with your updates.*
Now, you are ready to work (see [Quickstart](#quickstart)).
### Docker application image delivery
> ***Note:** this step is **useless** if you are working on a python package/Library/Framework to share (ie, not
> an application) because in these cases you want to publish your sdist or/and wheel archive(s).*
#### Build your docker image
PYMSDL template provides a Dockerfile in order to build an image for your application based on a generated `wheel`
distribution (See: [Dockerfile](docker/app/Dockerfile))).
> ***Note:** this Dockerfile is a "generic" one in order to provide a starting docker image distribution solution. You
> can (/should) update (/rewrite) it in order to adapt it to your application (see:
> [Best practices for writing Dockerfiles](https://docs.docker.com/develop/develop-images/dockerfile_best-practices/)).*
> **Build image command:**
> ```sh
> docker build \
> -f docker/app/Dockerfile \
> -t <DOCKER_IMG_NAME>:<VERSION> \
> --build-arg wheel_name=<WHEEL_NAME> \
> --build-arg entrypoint=<ENTRYPOINT_VALUE> \
> --build-arg cmd=<CMD_VALUE> \
> .
> ```
Where:
* `<DOCKER_IMG_NAME>`: Is your docker image name
* `<VERSION>`: Is your docker image version
* `<WHEEL_NAME>`: ***[REQUIRED]*** Is the `wheel` archive name to install from the `dist` directory
* `<ENTRYPOINT_VALUE>`: *[OPTIONAL: default is `python`]* Is the docker file ENTRYPOINT
* `<CMD_VALUE>`: *[OPTIONAL: default cmd is empty]* Is the dockerfile CMD
> ***Note:** Obviously, this command must be executed after the [Wheel archive](#wheel-archive) one.*
> ***Note:** Using an `entrypoint` with an empty `cmd` provides the possibility for the end user to use `cmd` as your
> project parameters (argv). Moreover, you can use `cmd` in order to define your default project parameters.*
> **Example with the provided `hellopymsdl` sample application:**
>
> First we create a wheel archive with `./project.py wheel`.
>
> ***Note:** your `dist` directory can contain several versions (/`wheel` archives)*
>
> **- Build docker image from *python entry point* example:**
>
> The `hellopymsdl` project provides an `hello` entry point (See: [pyproject.toml](./pyproject.toml)).
> ```sh
> docker build \
> -f docker/app/Dockerfile \
> -t hellopymsdl:2.9.10 \
> --build-arg wheel_name=hellopymsdl-2.9.10-py3-none-any.whl \
> --build-arg entrypoint=hello \
> .
> ```
>
> **- Build docker image from *module* example:**
> ```sh
> docker build \
> -f docker/app/Dockerfile \
> -t hellopymsdl:2.9.10 \
> --build-arg wheel_name=hellopymsdl-2.9.10-py3-none-any.whl \
> --build-arg entrypoint="python -m hellopymsdl.__main__" \
> .
> ```
> Run the `__main__.py` module from `hellopymsdl` package.
>
> **- Build docker image from *package* example:**
>
> The `hellopymsdl` project provided an `hello` entry point (See: [pyproject.toml](./pyproject.toml)).
> ```sh
> docker build \
> -f docker/app/Dockerfile \
> -t hellopymsdl:2.9.10 \
> --build-arg wheel_name=hellopymsdl-2.9.10-py3-none-any.whl \
> --build-arg entrypoint="python -m hellopymsdl" \
> .
> ```
> ***Note:** your package MUST contains a `__main__.py` module.*
>
> **- Build docker image without `entrypoint` build-arg:**
>
> if you don't define the `entrypoint` build-arg, the default one is `python`. So if you run your image
> without any argument (or `cmd` build-arg) it will open a python console in an environment where your project is
> installed
> ***Trick:** If you want to build the last updated wheel (not the last version but the last built archive) you can use
> `--build-arg wheel_name=$(ls -1At dist/ | head -1)`*
#### Run your docker image
Once your docker image is ready, you can run it
> ```sh
> docker run --rm <DOCKER_IMG_NAME>:<VERSION>
> ```
Where:
* `<DOCKER_IMG_NAME>`: Is your docker image name
* `<VERSION>`: Is your docker image version
> **Example with the provided `hellopymsdl` sample application:**
> ```
> docker run --rm --name hellopymsdl hellopymsdl:2.9.10
> ```
>
> ***Note:** Since we used only the `entrypoint` build-arg in our previous samples, if you have to pass arguments (argv)
> to your project you can do it directly like this:*
> ```
> docker run --rm --name hellopymsdl hellopymsdl:2.9.10 arg-1 arg-2 ... arg-N
> ```
>
> *Moreover, you can define default values for your project parameters. To do that, you have to use the `cmd` build-arg
> like this:*
> ```sh
> docker build \
> -f docker/app/Dockerfile \
> -t hellopymsdl:2.9.10 \
> --build-arg wheel_name=hellopymsdl-2.9.10-py3-none-any.whl \
> --build-arg entrypoint=hello \
> --build-arg cmd="arg-1 arg-2 ... arg-N" \
> .
> ```
> ***Note:** You can override the default `cmd` by using the previous command line sample.*
#### Push your docker image
In order to push your image into a repository (like [Docker Hub](https://hub.docker.com/)), you will have to use the
`docker push` command line.
See [Docker repositories](https://docs.docker.com/docker-hub/repos/)
## Workflows
The PYMSDL template provides a simple [GitHub Actions](https://github.com/features/actions) workflow in order to check
and manage your project (See: [.github](.github)).
### CI
This workflow is executed on *pull_request* or *push on main*. It aims to check your project quality. To do that the
following steps are executed:
* Build archives
* Lint
* Unit tests
* Mutation tests
* Check dependencies vulnerabilities
See: [ci.yml](.github/workflows/ci.yml)
> ***Note:** if you want to reuse the
>  badge for
> your project, don't forget to update the link.*
### On_release
This workflow is used in order to publish your project into [pypi](https://pypi.org/).
By default, PYMSDL template try to publish your project into [pypi](https://pypi.org/) when you publish a new release.
> ***Note:** A `PYPI_API_TOKEN` secret must be configured as pipy API key
> (See: [pypi api token](https://pypi.org/help/#apitoken)).*
> **<img src="https://upload.wikimedia.org/wikipedia/commons/thumb/1/17/Warning.svg/25px-Warning.svg.png" alt="warning-icon" width="20px" height="20px"/>
> WARNING:** [pypi](https://pypi.org/) doesn't allow to override an existing package version. You have to update your
> project version in the [pyproject.toml](./pyproject.toml) file to a not existing one before publish a new release.
> Otherwise, the workflow will fail.
> ***Note:** This workflow doesn't execute tests again because released version should be on `main` branch and this
> branch is configured to be protected (only pull requests can be merged on it which implies the [CI workflow](#ci) is
> executed first).*
See: [on_release.yml](.github/workflows/on_release.yml).
> ***Note:** if you want to reuse the
>  badge for your
> project, don't forget to update the link.*
You can find the `hellopymsdl` sample project published [here](https://pypi.org/project/hellopymsdl/)
> ***Note:** it means you can run `pip install hellopymsdl`.*
### Weekly_checks
This workflow is provided in order to do scheduled checks.
By default, PYMSDL template weekly checks your project dependencies in order to detect vulnerabilities even if you are
not working on you project (i.e.: [CI workflow](#ci) is not executed).
See: [weekly_checks.yml](.github/workflows/weekly_checks.yml).
> ***Note:** if you want to reuse the
> 
> badge for your project, don't forget to update the link.*
Raw data
{
"_id": null,
"home_page": "https://github.com/dev4py/pymsdl_template",
"name": "hellopymsdl",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.10,<4.0",
"maintainer_email": "",
"keywords": "peotry,maven,standard,directory,layout",
"author": "author",
"author_email": "author@mail.com",
"download_url": "https://files.pythonhosted.org/packages/fe/d7/4fcce36c880926c5df924bc43f38dca2f36dec40024371d2543eacd7c31f/hellopymsdl-2.9.10.tar.gz",
"platform": null,
"description": "# PYMSDL_Template\n\n***PYMSDL<sup>(PYthon Maven Standard Directory Layout)</sup> template*** is a\nPython [Poetry](https://python-poetry.org/) template inspired from\nthe [Maven Standard Directory Layout](https://maven.apache.org/guides/introduction/introduction-to-the-standard-directory-layout.html)\n.\n\n[](https://github.com/dev4py/pymsdl_template/actions/workflows/ci.yml) <br/>\n[](https://github.com/dev4py/pymsdl_template/actions/workflows/on_release.yml) <br/>\n[](https://github.com/dev4py/pymsdl_template/actions/workflows/weekly_checks.yml) <br/>\n[](https://www.python.org/) <br/>\n[](https://python-poetry.org/) <br/>\n[](https://github.com/St4rG00se) <br/>\n <br/>\n[](https://opensource.org/licenses/Apache-2.0)\n\n**<img src=\"https://upload.wikimedia.org/wikipedia/commons/thumb/1/17/Warning.svg/25px-Warning.svg.png\" alt=\"warning-icon\" width=\"20px\" height=\"20px\"/>\nWARNING Prerequisites:**\n\n* `Python >= 3.10.1`\n* `Poetry >= 1.1.0`\n\n***Since there are some existing limitations, it is strongly advised to read\nthe [Project organization](#project-organization) part before the [Project commands](#project-commands) one.***\n\n> ***Note:** this template is configured in order to work with [Poetry](https://python-poetry.org/).*\n>\n> *if you want to use another layout than [Maven Standard Directory Layout](https://maven.apache.org/guides/introduction/introduction-to-the-standard-directory-layout.html),\n> you can change the **project structure** as explained in the\n> [pyproject.toml & project.py files](#pyprojecttoml--projectpy-files) part.*\n\n## Table of contents\n\n* [Quickstart](#quickstart)\n + [Create a new project](#create-a-new-project)\n - [1. Click on Use this template](#1-click-on-use-this-template)\n - [2. Fork this template](#2-fork-this-template)\n - [3. Clone/download this template](#3-clonedownload-this-template)\n + [Prepare your environment](#prepare-your-environment)\n + [Test your setup](#test-your-setup)\n + [Manage your project](#manage-your-project)\n + [Let's dev](#lets-dev)\n* [Project organization](#project-organization)\n + [pyproject.toml & project.py files](#pyprojecttoml--projectpy-files)\n + [Maven Standard Directory Layout with python](#maven-standard-directory-layout-with-python)\n - [Sources & Resources directories configuration](#sources--resources-directories-configuration)\n - [<span style='color: orange'><img src=\"https://upload.wikimedia.org/wikipedia/commons/thumb/1/17/Warning.svg/25px-Warning.svg.png\" alt=\"warning-icon\" width=\"20px\" height=\"20px\"/> WARNING: Limitations</span>](#-warning-limitations)\n * [A. Use root package names with suffix](#a-use-root-package-names-with-suffix)\n * [B. Use namespace package as root package](#b-use-namespace-package-as-root-package)\n * [C. Don't fully respect the Maven Standard Directory Layout](#c-dont-fully-respect-the-maven-standard-directory-layout)\n* [Project commands](#project-commands)\n + [Clean project](#clean-project)\n + [Run module](#run-module)\n + [Run tox](#run-tox)\n + [Run linter](#run-linter)\n + [Run tests](#run-tests)\n + [Run type check](#run-type-check)\n + [Run mutation](#run-mutation)\n + [Build](#build)\n - [Wheel archive](#wheel-archive)\n - [Source Distribution](#source-distribution-archive)\n + [Delivery *(on https://pypi.org/)*](#delivery-on-httpspypiorg)\n* [Docker](#docker)\n + [Dev environment](#dev-environment)\n - [Build the pymsdl:devenv docker image](#build-the-pymsdldevenv-docker-image)\n - [Run the pymsdl:devenv environment](#run-the-pymsdldevenv-environment)\n + [Docker application image delivery](#docker-application-image-delivery)\n - [Build your docker image](#build-your-docker-image)\n - [Run your docker image](#run-your-docker-image)\n - [Push your docker image](#push-your-docker-image)\n* [Workflows](#workflows)\n + [CI](#ci)\n + [On_release](#on_release)\n + [Weekly_checks](#weekly_checks)\n\n## Quickstart\n\n### Create a new project\n\nThere are several ways to use this template for your project:\n\n#### 1. Click on [Use this template](https://github.com/dev4py/pymsdl_template/generate)\n\nCreate a new project from the [Use this template](https://github.com/dev4py/pymsdl_template/generate) button is the\nstandard way for a new GitHub project from a template.\n\nSee: [Creating a repository from a template](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-repository-from-a-template)\n\n> ***Note:** You have to be logged in*\n\n#### 2. Fork this template\n\nCreate a new project by forking the template is the \"old way\" to work with templates on GitHub.\n\nHowever, there are some differences between \"fork\" and \"use template\"\nexplained [here](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-repository-from-a-template)\nwhich can help you about your choice.\n\nSee: [About forks](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/about-forks)\n\n#### 3. Clone/download this template\n\nThis is a way to use if you are creating a new project but, you are not working on GitHub.\n\n### Prepare your environment\n\nPYMSDL template requires `Python >= 3.10.1` and `Poetry >= 1.1.0`.\n\n**If your environment is not ready yet, a docker ready to work environment is provided\n(see [Dev environment](#dev-environment)).**\n\nIn order to simplify your pipeline evolution and local use, this template provides you a python script with basic\nmanagement commands. See: [Project commands](#project-commands).\n\nYou have to run this command line in order to download your project dependencies:\n\n> ```sh\n> ./project.py load_deps\n> ```\n\n### Test your setup\n\nPYMSDL template provides a simple sample project named `hellopymsdl`. You can test your setup by running this command\nline:\n\n> ```sh\n> ./project.py test\n> ```\n\n### Manage your project\n\nSince this template use [Poetry](https://python-poetry.org/) you have to learn each\n[poetry command](https://python-poetry.org/docs/cli/).\n\nMoreover, this template provides you a python script with basic management commands.\nSee: [Project commands](#project-commands)\n\n> ***Note** [Project commands](#project-commands) samples should work on the provided `hellopymsdl` simple sample\n> project.*\n\n### Let's dev\n\nOnce previous steps are done you can start your developments by respecting the content\nof [Project organization](#project-organization) part.\n\n## Project organization\n\n### pyproject.toml & project.py files\n\nThe [pyproject.toml](./pyproject.toml) file is used in order to describe and deliver correctly your project.\n\nSee:\n\n* [PEP 517 \u2013 A build-system independent format for source trees](https://www.python.org/dev/peps/pep-0517/)\n* [PEP 518 \u2013 Specifying Minimum Build System Requirements for Python Projects](https://www.python.org/dev/peps/pep-0518/)\n* [PEP 621 \u2013 Storing project metadata in pyproject.toml](https://www.python.org/dev/peps/pep-0621/)\n* [PEP 660 \u2013 Editable installs for pyproject.toml based builds (wheel based)](https://www.python.org/dev/peps/pep-0660/)\n* [Poetry pyproject.toml details](https://python-poetry.org/docs/pyproject/)\n\nMoreover, this template provides the [project.py](./project.py) file which is a command line wrapper in order to\nsimplify the project evolution (see [Project commands](#project-commands)).\n\nWhen you start a new project from this template, ***YOU DON'T HAVE TO UPDATE THE [PROJECT.PY](./project.py) FILE***,\nuntil you switch from [Poetry](https://python-poetry.org/) to another tool.\n\nIn order to set your project properties, you just have to update the [pyproject.toml](./pyproject.toml).\n\n> **Note:** If you don't want to use the [Maven Standard Directory Layout](https://maven.apache.org/guides/introduction/introduction-to-the-standard-directory-layout.html),\n> you can reconfigure the project structure by replacing each `/src/main/...` or `/src/test/...` by your structure in\n> the [pyproject.toml](./pyproject.toml) file.\n\n### Maven Standard Directory Layout with python\n\n#### Sources & Resources directories configuration\n\nThis template attempts to reach\nthe [Maven Standard Directory Layout](https://maven.apache.org/guides/introduction/introduction-to-the-standard-directory-layout.html)\nfor python.\n\nThat's why you will find the following directory structure:\n\n* ***src/main/python:*** Should contains your application sources\n* ***src/main/resources:*** Should contains your application resources\n* ***src/test/python:*** Should contains your application **test** sources\n* ***src/test/resources:*** Should contains your application **test** resources\n\n**Sources** and **resources** directories must be in\nyour **[PYTHONPATH](https://docs.python.org/3/using/cmdline.html#envvar-PYTHONPATH).**\n\n**However, if you don't want to configure your PYTHONPATH, you can use the provided [Run module](#run-module) command.**\n\n> ***Note:** if you are using IDE like **[<img src=\"https://upload.wikimedia.org/wikipedia/commons/1/1d/PyCharm_Icon.svg\" alt=\"Pycharm-icon\" width=\"17px\" height=\"17px\"/>\nPycharm](https://www.jetbrains.com/pycharm/)**\n> , it means `src/main/python` and `src/main/resources` must be marked as **Sources Root**\n> `(Right click on these directories > Mark directory as > Sources Root)`\n> and `src/test/python` and `src/test/resources` must be marked as **Test Sources Root**\n> `(Right click on these directories > Mark directory as > Test Sources Root)`.*\n\n> ***Note:** Due to a [Poetry](https://python-poetry.org/) limitation, using installation with edit mode\n> (`pip install -e .`) in order to avoid the\n> [PYTHONPATH](https://docs.python.org/3/using/cmdline.html#envvar-PYTHONPATH) configuration will not work and fail\n> with:*\n>\n> `build backend is missing the 'build_editable' ... Consider using a build backend that supports PEP 660.`\n\n#### <span style='color: orange'><img src=\"https://upload.wikimedia.org/wikipedia/commons/thumb/1/17/Warning.svg/25px-Warning.svg.png\" alt=\"warning-icon\" width=\"20px\" height=\"20px\"/> WARNING: Limitations</span>\n\nPython resources MUST be located in a python package (i.e.: directory containing an `__init__.py` file). (You can see\nthat like a java classpath.)\n\nSince a package sources cannot be split in several directories, each package in `src/main/python`,\n`src/main/resources`, `src/test/python` and `src/test/resources` directories must be different. In case of conflict, the\npackage from the first directory found in\nyour **[PYTHONPATH](https://docs.python.org/3/using/cmdline.html#envvar-PYTHONPATH)** will be used.\n\nSo if you want to respect the\n*[Maven Standard Directory Layout](https://maven.apache.org/guides/introduction/introduction-to-the-standard-directory-layout.html)*\nthere are several suggestions:\n\n##### A. Use root package names with suffix\n\nUse root package names with suffixes like this:\n\n* *<My_Root_Package_Name>* for sources (in `src/main/python`)\n* *<My_Root_Package_Name>`_rsrc`* for resources (in `src/main/resources`)\n* *<My_Root_Package_Name>`_test`* for test sources (in `src/test/python`)\n* *<My_Root_Package_Name>`_test_rsrc`* for test resources (in `src/test/resources`)\n\n> **Project structure example:**\n>\n> ```sh\n> <My_Project>\n> |- ...\n> |- src\n> |- main\n> | |- python\n> | | |- <MY_ROOT_PACKAGE_NAME>\n> | | |- __init__.py\n> | | |- ...\n> | |- resources\n> | |- <MY_ROOT_PACKAGE_NAME>_rsrc\n> | |- __init__.py\n> | |- ...\n> |- test\n> |- python\n> | |- <MY_ROOT_PACKAGE_NAME>_test\n> | |- __init__.py\n> | |- ...\n> |- resources\n> |- <MY_ROOT_PACKAGE_NAME>_test_rsrc\n> |- __init__.py\n> |- ...\n> ```\n\n> ***Note:** since root package names are different (`_rsrc`, `_test`, `_test_rsrc` suffixes) it cannot exist conflict\n> between packages in `src/main/python`, `src/main/resources`, `src/test/python` and `src/test/resources`.*\n\n> ***Note:** `_rsrc`, `_test`, `_test_rsrc` are just suggested suffixes you can use your own suffixes.*\n\n##### B. Use namespace package as root package\n\nIf you really want a common root package name, you can use a `namespace package` as root. This `namespace package` must\ncontain packages without conflict between sources and resources directories.\n\n> *Reminder: A namespace package doesn't contain any source or `__init__.py` file.*\n\n> **Project structure with namespace package as root package example:**\n>\n> ```sh\n> <My_Project>\n> |- ...\n> |- src\n> |- main\n> | |- python\n> | | |- <MY_ROOT_NAMESPACE_PACKAGE_NAME>\n> | | |- <MY_PACKAGE_NAME>\n> | | | |- __init__.py\n> | | | |- ...\n> | | |- ...\n> | |- resources\n> | |- <MY_ROOT_NAMESPACE_PACKAGE_NAME>\n> | |- <MY_PACKAGE_NAME>_rsrc\n> | | |- __init__.py\n> | | |- ...\n> | |- ...\n> |- test\n> |- python\n> | |- <MY_ROOT_NAMESPACE_PACKAGE_NAME>\n> | |- <MY_PACKAGE_NAME>_test\n> | | |- __init__.py\n> | | |- ...\n> | |- ...\n> |- resources\n> |- <MY_ROOT_NAMESPACE_PACKAGE_NAME>\n> |- <MY_PACKAGE_NAME>_test_rsrc\n> | |- __init__.py\n> | |- ...\n> |- ...\n> ```\n\n##### C. Don't fully respect the Maven Standard Directory Layout\n\nIf you are not agree with the previous suggestions, you can remove the `src/main/resources`, `src/test/python`\nand `src/test/resources` directories and put your resources and tests directly into the `src/main/python` directory.\n\n> **Note:** if you do that, your tests will be included during your project/package installation (not only in the source\n> distribution as it is suggested in the best practices).\n\n## Project commands\n\nProject commands are available from the [project.py](./project.py) python file.\n\nIf you take a look at this file, you will see that it contains:\n\n* **A shared `project_properties` variable** which contains all project properties.\n\n* **A command line wrapper:** this wrapper is designed in order to be used locally and in your deployment scripts (like\n CI/CD).\n\n Indeed, by using it, if you want to update you \"project tools\" (sample: switching from poetry to setuptools) you just\n have to update this script but not all your pipeline.\n\n Moreover, this wrapper manage the project [PYTHONPATH](https://docs.python.org/3/using/cmdline.html#envvar-PYTHONPATH)\n for you.\n\n > **Command wrapper man:**\n > ```sh\n > PROJECT COMMANDS WRAPPER:\n > \n > Usage: python project.py <COMMAND_1> <arg1_1 ...> ... <COMMAND_N> <argN_1 ...>\n > Note: In order to get the wrapped command help, you can try python project.py <command> --help\n > \n > Available commands are:\n > load_deps Install all dependencies (dev included)\n > clean Remove directories generated by the \"build\" commands (like 'sdist' or 'wheel')\n > run Run module which can be in the project structure without having to configure the PYTHONPATH\n > tox Run tox\n > lint Run linter\n > test Run configured unit tests\n > typing Run typing checker\n > mut Run mutation tests\n > wheel Build Wheel archive\n > sdist Build sdist archive\n > upload Upload available deliveries\n > ```\n\n > ***Note:** Using `--help` argument on a command or if an error occurs, the message will be from the wrapped command\n > line.*\n\n### Load dependencies\n\n> ```sh\n> ./project.py load_deps\n> ```\nor\n> ```sh\n> python project.py load_deps\n> ```\n\n### Clean project\n\n> ```sh\n> ./project.py clean\n> ```\nor\n> ```sh\n> python project.py clean\n> ```\n\n> ***Note:** Remove dist directory and test cache directories.*\n\n### Run module\n\nPYMSDL template provides you a run python module command line (even in the **project packages**) without having to\nconfigure your **[PYTHONPATH](https://docs.python.org/3/using/cmdline.html#envvar-PYTHONPATH)**:\n\n> ```sh\n> ./project.py run -m <MODULE_NAME>\n> ```\nor\n> ```sh\n> python project.py run -m <MODULE_NAME>\n> ```\n\n> ***Note:** the `run` command is like opening python in your poetry virtual environment and the project structure\n> configured in your **[PYTHONPATH](https://docs.python.org/3/using/cmdline.html#envvar-PYTHONPATH).***\n>\n> *Moreover, your opened `python` will work from the current directory (not from the `project.py` one).*\n\n> **Examples:**\n>\n> **- Open a *python console* from the current directory:**\n> ```\n> ./project.py run\n> ```\n> ***Note:** `<PATH_TO_PROJECT.PY> run` will open a python console in your current directory not in the `project.py`\n> one.*\n>\n> **- Run *module* example:**\n> ```sh\n> ./project.py run -m hellopymsdl.__main__\n> ```\n> Run the `__main__.py` module from `hellopymsdl` package.\n>\n> **- Run *package* example:**\n> ```sh\n> ./project.py run -m hellopymsdl\n> ````\n> ***Note:** your package MUST contains a `__main__.py` module.*\n>\n> **- Run *module* from path example:**\n> ```sh\n> ./project.py run src/main/python/hellopymsdl/__main__.py\n> ```\n> Run the `__main__.py` module from `hellopymsdl` package.\n> **WARNING: the path is from the command `CWD` if not absolute.**\n>\n> **- Run *package* from path example:**\n> ```sh\n> ./project.py run src/main/python/hellopymsdl\n> ```\n> ***Note:** your package MUST contains a `__main__.py` module.*\n> **WARNING: the path is from the command `CWD` if not absolute.**\n>\n> **- Run *module* with arguments example (using --args string parameter):**\n> ```sh\n> ./project.py run -m hellopymsdl.__main__ --arg1 --arg2=my_arg2 ...\n> ```\n\n### Run tox\n\nPYMSDL template uses [tox](https://tox.wiki/) in order to manage your tests (unit tests, lint, etc.)\n\n> ```sh\n> ./project.py tox\n> ```\nor\n> ```sh\n> python project.py tox\n> ```\n\n> ***Note:** You will find the [tox](https://tox.wiki/) configuration in the [pyproject.toml](./pyproject.toml) file\n> (`[tool.tox]` section).*\n>\n> The default [tox](https://tox.wiki/) configuration provides the following `envlist`:\n>\n>* ***pylint:*** Executes the configured linter\n>* ***covclean:*** Cleans the coverage reports\n>* ***py310:*** Executes the configured test runner under python 3.10\n>* ***report:*** Generates console, html and xml reports\n>* ***mutation:*** Executes mutation testing and generate reports\n>\n> Moreover, the provided configuration runs each test on INSTALLED packages (Not on the given sources even if obviously\n> the installed packages depends on the given sources). The goal is to test definitive installed versions.\n\n### Run linter\n\n> ```sh\n> ./project.py lint\n> ```\nor\n> ```sh\n> python project.py lint\n> ```\n\n> ***Note:** `json` and `txt` reports will be available in `build/reports/lint`.*\n\n> ***Note:** By default this template uses [pylint](https://pylint.org/) as linter. You will find the linter\n> configuration in the [pyproject.toml](./pyproject.toml) file (`[tool.pylint....]` sections).*\n\n> ***Note:** This command uses [tox](#run-tox) but only in order to call the linter.*\n\n### Run tests\n\nThis project is configured to execute tests with [**Pytest**](https://docs.pytest.org/):\n\n> ```sh\n> ./project.py test\n> ```\nor\n> ```sh\n> python project.py test\n> ```\n\n> ***Note:** `html`, `json` and `xml` reports will be available in `build/reports/coverage`.*\n\n> ***Note:** If you change the project structure, don't forget to update the `[tool.pytest.ini_options]` section from\n> the [pyproject.toml](./pyproject.toml) file.*\n\n> ***Note:** This command uses [tox](#run-tox) but only in order to run your tests.*\n\n### Run type check\n\nPYMSDL template provides a static type checker by using [**mypy**](http://mypy-lang.org/).\n\nSee:\n\n* [PEP 484 \u2013 Type Hints](https://peps.python.org/pep-0484/)\n* [PEP 526 \u2013 Syntax for Variable Annotations](https://peps.python.org/pep-0526/)\n\n> ```sh\n> ./project.py typing\n> ```\nor\n> ```sh\n> python project.py typing\n> ```\n\n> ***Note:** Reports will be available in `build/reports/typing`.*\n\n> ***Note:** If you change the project structure, don't forget to update the [pyproject.toml](./pyproject.toml) file\n> (`[tool.tox]` and `[tool.mypy]` sections).*\n\n> ***Note:** This command uses [tox](#run-tox) but only in order to call the type checker (by default: `mypy`).*\n\n### Run mutation\n\nThis template provides mutation testing by using [**mutmut**](https://mutmut.readthedocs.io/en/latest/):\n\n> ```sh\n> ./project.py mut\n> ```\nor\n> ```sh\n> python project.py mut\n> ```\n\n> ***Note:** `html` report will be available in `build/reports/mutation`.*\n\n> ***Note:** If you change the project structure, don't forget to update the [pyproject.toml](./pyproject.toml) file.*\n\n> ***Note:** This command uses [tox](#run-tox) but only in order to run your tests.*\n\n### Build\n\n#### Wheel archive\n\n> ```sh\n> ./project.py wheel\n> ```\nor\n> ```sh\n> python project.py wheel\n> ```\n\n#### Source Distribution archive\n\nIf you need a source distribution (sdist) archive:\n\n> ```sh\n> ./project.py sdist\n> ```\nor\n> ```sh\n> python project.py sdist\n> ```\n\n### Delivery *(on https://pypi.org/)*\n\n> ```sh\n> ./project.py upload\n> ```\nor\n> ```sh\n> python project.py upload\n> ```\n\n> ***Note:** Obviously, this command must be executed after the [Build](#build) one.*\n\n## Docker\n\n**<img src=\"https://upload.wikimedia.org/wikipedia/commons/thumb/1/17/Warning.svg/25px-Warning.svg.png\" alt=\"warning-icon\" width=\"20px\" height=\"20px\"/>\nWARNING This part requires [docker](https://www.docker.com/) to be installed**\n\n### Dev environment\n\nIf you haven't a python/poetry environment installed, PYMSDL template provides you a \"ready to work\" Dockerfile:\n\n#### Build the pymsdl:devenv docker image\n\n> ```sh\n> docker build -t pymsdl:devenv-1.0.0 -f docker/devenv/Dockerfile .\n> ```\n\n#### Run the pymsdl:devenv environment\n\n> ```sh\n> docker run --rm -it --name pymsdl-dev-env -v ${PWD}:/app pymsdl:devenv-1.0.0\n> ```\n\nIt opens a `sh` on a well configured python/poetry environment.\n\n> ***Note:** you have to use the volume (`-v`) option in order to mount your project files into the container `/app`\n> directory. This is useful for staying up to date with your updates.*\n\nNow, you are ready to work (see [Quickstart](#quickstart)).\n\n### Docker application image delivery\n\n> ***Note:** this step is **useless** if you are working on a python package/Library/Framework to share (ie, not\n> an application) because in these cases you want to publish your sdist or/and wheel archive(s).*\n\n#### Build your docker image\n\nPYMSDL template provides a Dockerfile in order to build an image for your application based on a generated `wheel`\ndistribution (See: [Dockerfile](docker/app/Dockerfile))).\n\n> ***Note:** this Dockerfile is a \"generic\" one in order to provide a starting docker image distribution solution. You\n> can (/should) update (/rewrite) it in order to adapt it to your application (see:\n> [Best practices for writing Dockerfiles](https://docs.docker.com/develop/develop-images/dockerfile_best-practices/)).*\n\n> **Build image command:**\n> ```sh\n> docker build \\\n> -f docker/app/Dockerfile \\\n> -t <DOCKER_IMG_NAME>:<VERSION> \\\n> --build-arg wheel_name=<WHEEL_NAME> \\\n> --build-arg entrypoint=<ENTRYPOINT_VALUE> \\\n> --build-arg cmd=<CMD_VALUE> \\\n> .\n> ```\n\nWhere:\n\n* `<DOCKER_IMG_NAME>`: Is your docker image name\n* `<VERSION>`: Is your docker image version\n* `<WHEEL_NAME>`: ***[REQUIRED]*** Is the `wheel` archive name to install from the `dist` directory\n* `<ENTRYPOINT_VALUE>`: *[OPTIONAL: default is `python`]* Is the docker file ENTRYPOINT\n* `<CMD_VALUE>`: *[OPTIONAL: default cmd is empty]* Is the dockerfile CMD\n\n> ***Note:** Obviously, this command must be executed after the [Wheel archive](#wheel-archive) one.*\n\n> ***Note:** Using an `entrypoint` with an empty `cmd` provides the possibility for the end user to use `cmd` as your\n> project parameters (argv). Moreover, you can use `cmd` in order to define your default project parameters.*\n\n> **Example with the provided `hellopymsdl` sample application:**\n>\n> First we create a wheel archive with `./project.py wheel`.\n>\n> ***Note:** your `dist` directory can contain several versions (/`wheel` archives)*\n>\n> **- Build docker image from *python entry point* example:**\n>\n> The `hellopymsdl` project provides an `hello` entry point (See: [pyproject.toml](./pyproject.toml)).\n> ```sh\n> docker build \\\n> -f docker/app/Dockerfile \\\n> -t hellopymsdl:2.9.10 \\\n> --build-arg wheel_name=hellopymsdl-2.9.10-py3-none-any.whl \\\n> --build-arg entrypoint=hello \\\n> .\n> ```\n>\n> **- Build docker image from *module* example:**\n> ```sh\n> docker build \\\n> -f docker/app/Dockerfile \\\n> -t hellopymsdl:2.9.10 \\\n> --build-arg wheel_name=hellopymsdl-2.9.10-py3-none-any.whl \\\n> --build-arg entrypoint=\"python -m hellopymsdl.__main__\" \\\n> .\n> ```\n> Run the `__main__.py` module from `hellopymsdl` package.\n>\n> **- Build docker image from *package* example:**\n>\n> The `hellopymsdl` project provided an `hello` entry point (See: [pyproject.toml](./pyproject.toml)).\n> ```sh\n> docker build \\\n> -f docker/app/Dockerfile \\\n> -t hellopymsdl:2.9.10 \\\n> --build-arg wheel_name=hellopymsdl-2.9.10-py3-none-any.whl \\\n> --build-arg entrypoint=\"python -m hellopymsdl\" \\\n> .\n> ```\n> ***Note:** your package MUST contains a `__main__.py` module.*\n>\n> **- Build docker image without `entrypoint` build-arg:**\n>\n> if you don't define the `entrypoint` build-arg, the default one is `python`. So if you run your image\n> without any argument (or `cmd` build-arg) it will open a python console in an environment where your project is\n> installed\n\n> ***Trick:** If you want to build the last updated wheel (not the last version but the last built archive) you can use\n> `--build-arg wheel_name=$(ls -1At dist/ | head -1)`*\n\n#### Run your docker image\n\nOnce your docker image is ready, you can run it\n\n> ```sh\n> docker run --rm <DOCKER_IMG_NAME>:<VERSION>\n> ```\n\nWhere:\n\n* `<DOCKER_IMG_NAME>`: Is your docker image name\n* `<VERSION>`: Is your docker image version\n\n> **Example with the provided `hellopymsdl` sample application:**\n> ```\n> docker run --rm --name hellopymsdl hellopymsdl:2.9.10\n> ```\n>\n> ***Note:** Since we used only the `entrypoint` build-arg in our previous samples, if you have to pass arguments (argv)\n> to your project you can do it directly like this:*\n> ```\n> docker run --rm --name hellopymsdl hellopymsdl:2.9.10 arg-1 arg-2 ... arg-N\n> ```\n>\n> *Moreover, you can define default values for your project parameters. To do that, you have to use the `cmd` build-arg\n> like this:*\n> ```sh\n> docker build \\\n> -f docker/app/Dockerfile \\\n> -t hellopymsdl:2.9.10 \\\n> --build-arg wheel_name=hellopymsdl-2.9.10-py3-none-any.whl \\\n> --build-arg entrypoint=hello \\\n> --build-arg cmd=\"arg-1 arg-2 ... arg-N\" \\\n> .\n> ```\n> ***Note:** You can override the default `cmd` by using the previous command line sample.*\n\n#### Push your docker image\n\nIn order to push your image into a repository (like [Docker Hub](https://hub.docker.com/)), you will have to use the\n`docker push` command line.\n\nSee [Docker repositories](https://docs.docker.com/docker-hub/repos/)\n\n## Workflows\n\nThe PYMSDL template provides a simple [GitHub Actions](https://github.com/features/actions) workflow in order to check\nand manage your project (See: [.github](.github)).\n\n### CI\n\nThis workflow is executed on *pull_request* or *push on main*. It aims to check your project quality. To do that the\nfollowing steps are executed:\n\n* Build archives\n* Lint\n* Unit tests\n* Mutation tests\n* Check dependencies vulnerabilities\n\nSee: [ci.yml](.github/workflows/ci.yml)\n\n> ***Note:** if you want to reuse the\n>  badge for\n> your project, don't forget to update the link.*\n\n### On_release\n\nThis workflow is used in order to publish your project into [pypi](https://pypi.org/).\n\nBy default, PYMSDL template try to publish your project into [pypi](https://pypi.org/) when you publish a new release.\n\n> ***Note:** A `PYPI_API_TOKEN` secret must be configured as pipy API key\n> (See: [pypi api token](https://pypi.org/help/#apitoken)).*\n\n> **<img src=\"https://upload.wikimedia.org/wikipedia/commons/thumb/1/17/Warning.svg/25px-Warning.svg.png\" alt=\"warning-icon\" width=\"20px\" height=\"20px\"/>\n> WARNING:** [pypi](https://pypi.org/) doesn't allow to override an existing package version. You have to update your\n> project version in the [pyproject.toml](./pyproject.toml) file to a not existing one before publish a new release.\n> Otherwise, the workflow will fail.\n\n> ***Note:** This workflow doesn't execute tests again because released version should be on `main` branch and this\n> branch is configured to be protected (only pull requests can be merged on it which implies the [CI workflow](#ci) is\n> executed first).*\n\nSee: [on_release.yml](.github/workflows/on_release.yml).\n\n> ***Note:** if you want to reuse the\n>  badge for your\n> project, don't forget to update the link.*\n\nYou can find the `hellopymsdl` sample project published [here](https://pypi.org/project/hellopymsdl/)\n\n> ***Note:** it means you can run `pip install hellopymsdl`.*\n\n### Weekly_checks\n\nThis workflow is provided in order to do scheduled checks.\n\nBy default, PYMSDL template weekly checks your project dependencies in order to detect vulnerabilities even if you are\nnot working on you project (i.e.: [CI workflow](#ci) is not executed).\n\nSee: [weekly_checks.yml](.github/workflows/weekly_checks.yml).\n\n> ***Note:** if you want to reuse the\n> \n> badge for your project, don't forget to update the link.*\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "A Python template inspired from the Maven Standard Directory Layout",
"version": "2.9.10",
"split_keywords": [
"peotry",
"maven",
"standard",
"directory",
"layout"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "c464962f5dc1108e08e2c2500d94c8a90c5143dbf06fb39f1981e987b13e4b42",
"md5": "7982d6c757a902ce50040322f3831506",
"sha256": "aa5690222c1589bd3c5434107cf5bbe2ad7f20d6e8c756a751e5428d6a9cdc45"
},
"downloads": -1,
"filename": "hellopymsdl-2.9.10-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7982d6c757a902ce50040322f3831506",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10,<4.0",
"size": 14973,
"upload_time": "2023-01-24T10:16:01",
"upload_time_iso_8601": "2023-01-24T10:16:01.033392Z",
"url": "https://files.pythonhosted.org/packages/c4/64/962f5dc1108e08e2c2500d94c8a90c5143dbf06fb39f1981e987b13e4b42/hellopymsdl-2.9.10-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "fed74fcce36c880926c5df924bc43f38dca2f36dec40024371d2543eacd7c31f",
"md5": "874da1b7c2f4b7b062c0dbd0bf418f29",
"sha256": "1f7be83e8b47717b17f2c87b9c7f510646b6fcb9db362c6b4039b91c8f46709f"
},
"downloads": -1,
"filename": "hellopymsdl-2.9.10.tar.gz",
"has_sig": false,
"md5_digest": "874da1b7c2f4b7b062c0dbd0bf418f29",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10,<4.0",
"size": 34277,
"upload_time": "2023-01-24T10:16:02",
"upload_time_iso_8601": "2023-01-24T10:16:02.980849Z",
"url": "https://files.pythonhosted.org/packages/fe/d7/4fcce36c880926c5df924bc43f38dca2f36dec40024371d2543eacd7c31f/hellopymsdl-2.9.10.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-01-24 10:16:02",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "dev4py",
"github_project": "pymsdl_template",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "hellopymsdl"
}
JSON
