Merge pull request #779 from jbaptperez/lint-fixes-and-enhancements

Lint fixes and enhancements

CONTRIBUTING.md

@@ -1,70 +1,89 @@
 # Contributing to podman-compose
 
-## Who can contribute? 
+## Who can contribute?
 
-- Users that found a bug
+- Users that found a bug,
-- Users that wants to propose new functionalities or enhancements
+- Users that want to propose new functionalities or enhancements,
-- Users that want to help other users to troubleshoot their environments
+- Users that want to help other users to troubleshoot their environments,
-- Developers that want to fix bugs
+- Developers that want to fix bugs,
-- Developers that want to implement new functionalities or enhancements
+- Developers that want to implement new functionalities or enhancements.
 
 ## Branches
 
-Please request your PR to be merged into the `devel` branch. 
+Please request your pull request to be merged into the `devel` branch.
 Changes to the `stable` branch are managed by the repository maintainers.
 
 ## Development environment setup
 
 Note: Some steps are OPTIONAL but all are RECOMMENDED.
 
-1. Fork the project repo and clone it
+1. Fork the project repository and clone it:
-```shell
+
-$ git clone https://github.com/USERNAME/podman-compose.git
+   ```shell
-$ cd podman-compose
+   $ git clone https://github.com/USERNAME/podman-compose.git
-```
+   $ cd podman-compose
-1. (OPTIONAL) Create a python virtual environment. Example using [virtualenv wrapper](https://virtualenvwrapper.readthedocs.io/en/latest/): 
+   ```
-```shell
+
-mkvirtualenv podman-compose
+2. (OPTIONAL) Create a Python virtual environment. Example using
-```
+   [virtualenv wrapper](https://virtualenvwrapper.readthedocs.io/en/latest/):
-2. Install the project runtime and development requirements   
+
-```shell
+    ```shell
-$ pip install '.[devel]'
+    $ mkvirtualenv podman-compose
-```
+    ```
-3. (OPTIONAL) Install `pre-commit` git hook scripts (https://pre-commit.com/#3-install-the-git-hook-scripts)
+
-```shell
+3. Install the project runtime and development requirements:
-$ pre-commit install
+
-```
+   ```shell
-4. Create a new branch, develop and add tests when possible
+   $ pip install '.[devel]'
-5. Run linting & testing before committing code. Ensure all the hooks are passing.
+   ```
-```shell
+
-$ pre-commit run --all-files
+4. (OPTIONAL) Install `pre-commit` git hook scripts
-```
+   (https://pre-commit.com/#3-install-the-git-hook-scripts):
-6. Run code coverage
+
-```shell
+   ```shell
-coverage run --source podman_compose -m unittest pytests/*.py
+   $ pre-commit install
-python -m unittest tests/*.py
+   ```
-coverage combine
+
-coverage report
+5. Create a new branch, develop and add tests when possible.
-coverage html
+6. Run linting and testing before committing code. Ensure all the hooks are passing.
-```
+
-7. Commit your code to your fork's branch. 
+   ```shell
-   - Make sure you include a `Signed-off-by` message in your commits. Read [this guide](https://docs.github.com/en/authentication/managing-commit-signature-verification/signing-commits) to learn how to sign your commits 
+   $ pre-commit run --all-files
-   - In the commit message reference the Issue ID that your code fixes and a brief description of the changes. Example: `Fixes #516: allow empty network`
+   ```
-7. Open a PR to `containers/podman-compose:devel` and wait for a maintainer to review your work.
+
+7. Run code coverage:
+
+    ```shell
+    $ coverage run --source podman_compose -m unittest pytests/*.py
+    $ python -m unittest tests/*.py
+    $ coverage combine
+    $ coverage report
+    $ coverage html
+    ```
+
+8. Commit your code to your fork's branch.
+   - Make sure you include a `Signed-off-by` message in your commits.
+     Read [this guide](https://github.com/containers/common/blob/main/CONTRIBUTING.md#sign-your-prs)
+     to learn how to sign your commits.
+   - In the commit message, reference the Issue ID that your code fixes and a brief description of
+     the changes.
+     Example: `Fixes #516: Allow empty network`
+9. Open a pull request to `containers/podman-compose:devel` and wait for a maintainer to review your
+   work.
 
 ## Adding new commands
 
-To add a command you need to add a function that is decorated
+To add a command, you need to add a function that is decorated with `@cmd_run`.
-with `@cmd_run` passing the compose instance, command name and
-description. This function must be declared `async` the wrapped 
-function should accept two arguments the compose instance and 
-the command-specific arguments (resulted from python's `argparse` 
-package) inside that command you can run PodMan like this 
-`await compose.podman.run(['inspect', 'something'])`and inside 
-that function you can access `compose.pods` and `compose.containers` 
-...etc. Here is an example
 
-```
+The decorated function must be declared `async` and should accept two arguments: The compose
+instance and the command-specific arguments (resulted from the Python's `argparse` package).
+
+In this function, you can run Podman (e.g. `await compose.podman.run(['inspect', 'something'])`),
+access `compose.pods`, `compose.containers` etc.
+
+Here is an example:
+
+```python
 @cmd_run(podman_compose, 'build', 'build images defined in the stack')
 async def compose_build(compose, args):
     await compose.podman.run(['build', 'something'])
@@ -72,31 +91,36 @@ async def compose_build(compose, args):
 
 ## Command arguments parsing
 
-Add a function that accept `parser` which is an instance from `argparse`.
+To add arguments to be parsed by a command, you need to add a function that is decorated with
-In side that function you can call `parser.add_argument()`.
+`@cmd_parse` which accepts the compose instance and the command's name (as a string list or as a
-The function decorated with `@cmd_parse` accepting the compose instance,
+single string).
-and command names (as a list or as a string).
-You can do this multiple times. 
 
-Here is an example
+The decorated function should accept a single argument: An instance of `argparse`.
 
-```
+In this function, you can call `parser.add_argument()` to add a new argument to the command.
+
+Note you can add such a function multiple times.
+
+Here is an example:
+
+```python
 @cmd_parse(podman_compose, 'build')
 def compose_build_parse(parser):
     parser.add_argument("--pull",
         help="attempt to pull a newer version of the image", action='store_true')
     parser.add_argument("--pull-always",
-        help="attempt to pull a newer version of the image, Raise an error even if the image is present locally.", action='store_true')
+        help="Attempt to pull a newer version of the image, "
+             "raise an error even if the image is present locally.",
+        action='store_true')
 ```
 
-NOTE: `@cmd_parse` should be after `@cmd_run`
+NOTE: `@cmd_parse` should be after `@cmd_run`.
 
-## Calling a command from inside another
+## Calling a command from another one
 
-If you need to call `podman-compose down` from inside `podman-compose up`
+If you need to call `podman-compose down` from `podman-compose up`, do something like:
-do something like:
 
-```
+```python
 @cmd_run(podman_compose, 'up', 'up desc')
 async def compose_up(compose, args):
     await compose.commands['down'](compose, args)
@@ -104,8 +128,8 @@ async def compose_up(compose, args):
     await compose.commands['down'](argparse.Namespace(foo=123))
 ```
 
-
 ## Missing Commands (help needed)
+
 ```
   bundle             Generate a Docker bundle from the Compose file
   create             Create services

setup.py

@@ -40,7 +40,7 @@ setup(
         "pyyaml",
         "python-dotenv",
     ],
-    extras_require={"devel": ["ruff", "pre-commit", "coverage", "parameterize"]},
+    extras_require={"devel": ["ruff", "pre-commit", "coverage", "parameterized"]},
     # test_suite='tests',
     # tests_require=[
     #     'coverage',