common-python-tasks 0.0.3__tar.gz → 0.1.0__tar.gz

{common_python_tasks-0.0.3 → common_python_tasks-0.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: common-python-tasks
-Version: 0.0.3
+Version: 0.1.0
 Summary: Opinionated Poe the Poet tasks for Python package development.
 License-Expression: MIT
 License-File: LICENSE
@@ -16,11 +16,11 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Software Development :: Build Tools
 Requires-Dist: autoflake (>=2.3.1,<3.0.0)
-Requires-Dist: black (>=25.11.0,<26.0.0)
+Requires-Dist: black (>=26.3.1,<27.0.0)
 Requires-Dist: dunamai (>=1.25.0,<2.0.0)
 Requires-Dist: flake8 (>=7.3.0,<8.0.0)
 Requires-Dist: git-cliff (>=2.12.0,<3.0.0)
-Requires-Dist: isort (>=7.0.0,<8.0.0)
+Requires-Dist: isort (>=8.0.1,<9.0.0)
 Requires-Dist: jinja2 (>=3.1.6,<4.0.0)
 Requires-Dist: poethepoet-tasks (>=0.3.0,<0.4.0)
 Requires-Dist: pytest (>=9.0.1,<10.0.0)
@@ -35,6 +35,8 @@ Description-Content-Type: text/markdown
 
 This package is a collection of (very) opinionated [Poe the Poet](https://poethepoet.natn.io/guides/packaged_tasks.html) Python tasks for common Python development workflows.
 
+Instead of writing your own tasks for formatting, linting, testing, packaging, and more, you can use these pre-built tasks that work out of the box with reasonable defaults and support configuration overrides when needed. In the past, I found myself copying and pasting the same task definitions across projects, and this package is my attempt to DRY up that workflow and provide a single source of truth for common Python development tasks. I hope you can use them too.
+
 ## Quick start
 
 ### Automated setup
@@ -42,31 +44,40 @@ This package is a collection of (very) opinionated [Poe the Poet](https://poethe
 You can add `common-python-tasks` to a new project by using the handy automated installation script.
 
 ```shell
-curl -sSL https://api.github.com/repos/ci-sourcerer/common-python-tasks/contents/scripts/add-common-python-tasks.sh | jq -r '.content' | base64 -d | TAGS_TO_INCLUDE="format lint test" sh
+curl -sSL https://api.github.com/repos/ci-sourcerer/common-python-tasks/contents/scripts/add-common-python-tasks.sh | jq -r '.content' | base64 -d | sh
+```
+
+To install a specific release, set the environment variable `COMMON_PYTHON_TASKS_VERSION`.
+
+```shell
+COMMON_PYTHON_TASKS_VERSION=0.1.0 \
+  sh -c "$(curl -sSL https://api.github.com/repos/ci-sourcerer/common-python-tasks/contents/scripts/add-common-python-tasks.sh | jq -r '.content' | base64 -d)"
 ```
 
 This will complete the following steps.
 
 1. Add the latest version of `common-python-tasks` to your `pyproject.toml` dependencies
-2. Configure Poe the Poet to include only the tasks with the specified tags
+2. Configure Poe the Poet to expose the default common task set
 3. Install the package using Poetry
 
 **Always review scripts before running them!** Even though I believe I write good software, it's best practice to verify any script you download from the Internet.
 
 ### Manual setup
 
-1. Add `common-python-tasks` to your `pyproject.toml` and configure Poe the Poet to include the desired tasks
+There's no real reason to run the automated script; I just like automating everything. You can achieve the same result by following these steps.
+
+1. Add `common-python-tasks` to your `pyproject.toml` and configure Poe the Poet
 
     ```toml
     [project]
     name = "my-awesome-project"
-    version = "0.0.2"
+    version = "0.1.0"
     dependencies = [
-        "common-python-tasks==0.0.2",  # Always pin to a specific version
+        "common-python-tasks==0.1.0",  # Always pin to a specific version
     ]
 
     [tool.poe]
-    include_script = "common_python_tasks:tasks(include_tags=['format', 'lint', 'test'])"  # Include or exclude tasks by tags
+    include_script = "common_python_tasks:tasks()"  # Uses the default `common` task set
     ```
 
 2. Install the package
@@ -90,26 +101,26 @@ Internal tasks are used by other tasks and are not meant to be run directly.
 <!-- tasks-table -->
 | Task | Description | Tags |
 | - | - | - |
-| `build` | Build the project and its containers (when `containers` tag is included) | packaging, containers |
-| `build-image` | Build the container image for this project using the Dockerfile template (and configured extensions) | containers, build |
-| `build-package` | Build the package (wheel and sdist) | packaging, build |
-| `bump-version` | Bump the project version, defaulting to an inferred semantic bump from git history | packaging |
-| `changelog` | Print the changelog for the current version based on git history | packaging, release |
-| `clean` | Clean up temporary files and directories | clean |
-| `container-shell` | Run the debug image with an interactive shell | containers, debug |
-| `db-shell` | Open a psql shell to the database container | web, containers, database |
-| `format` | Format code with autoflake, black, and isort | format |
-| `lint` | Lint Python code with autoflake, black, isort, and flake8 | lint |
-| `publish-package` | Publish the package to the PyPI server | packaging |
-| `publish-github-release` | Publish or update a GitHub Release and attach built distribution assets | packaging, release |
-| `push-image` | Push the Docker image to the container registry | containers, packaging, release |
-| `release` | Run package release flow and publish containers when `containers` tag is included. Supports optional `RELEASE_PRE_SCRIPT` and `RELEASE_POST_SCRIPT` hooks. | packaging, release |
-| `reset-db` | Reset the database by deleting the database volume | web, containers, database |
-| `run-container` | Run the Docker image as a container | containers |
-| `run-db-migrations` | Run database migrations | web, containers, database |
-| `stack-down` | Bring down the development stack for the application | web, containers |
-| `stack-up` | Bring up the development stack for the application | web, containers |
-| `test` | Run the test suite with coverage | test |
+| `test` | Run the test suite with coverage (if `pytest-cov` is installed). | common, test |
+| `clean` | Clean up temporary files and directories. | clean, common |
+| `format` | Format Python code with autoflake, black, and isort. | common, format |
+| `lint` | Lint Python code with autoflake, black, isort, and flake8. | common, lint |
+| `build-image` | Build the container image for this project using the Dockerfile template. | build, containers |
+| `run-container` | Run the Docker image as a container for this project.  By default (when `tag` is `None`) this will run the most-recently-built tag for the project's image. | containers |
+| `push-image` | Push the Docker image for this project to the container registry. | containers, packaging, release |
+| `publish-package` | Publish the package to the PyPI server. | common, packaging |
+| `publish-github-release` | Publish or update a GitHub Release for the current repository. | common, packaging, release |
+| `build-package` | Build the package (wheel and sdist). | build, common, packaging |
+| `bump-version` | Bump the project version. | common, packaging |
+| `changelog` | Print the changelog for the current version based on git history and git-cliff. | common, packaging, release |
+| `release` | Run a full release flow for package and containers. | common, containers, packaging, release |
+| `build` | Build the project and its containers. | common, containers, packaging |
+| `stack-up` | Bring up the development stack for the application. | containers, fastapi, web |
+| `stack-down` | Bring down the development stack for the application. | containers, fastapi, web |
+| `reset-db` | Reset the database by deleting the database volume. | containers, database, fastapi, web |
+| `run-db-migrations` | Run database migrations. | containers, database, fastapi, web |
+| `db-shell` | Open a psql shell to the database container. | containers, database, fastapi, web |
+| `container-shell` | Run the debug image with an interactive shell. | containers, debug |
 <!-- end-tasks-table -->
 
 ## Docker Compose Development Stacks
@@ -237,9 +248,10 @@ The following environment variables configure package and container behavior.
 - `GITHUB_RELEASE_TAG` optional tag name to publish for the GitHub Release.
 - `GITHUB_RELEASE_NAME` optional release title to use for the GitHub Release.
 - `GITHUB_RELEASE_BODY` optional release body text to use for the GitHub Release.
+- `RELEASE_UPDATE_CHANGELOG` truthy value to update `CHANGELOG.md` with `git-cliff --tag "$RELEASE_TAG" --prepend CHANGELOG.md` before the release tag is created. This is enabled by default; set it to a falsy value to disable changelog commits during release.
 - `RELEASE_PRE_SCRIPT` optional shell command to run before the release steps.
 - `RELEASE_POST_SCRIPT` optional shell command to run after the release completes.
-- Hook commands receive the following env vars: `RELEASE_TAG`, `RELEASE_VERSION`, `RELEASE_STAGE`, `RELEASE_COMPONENT`, and `RELEASE_DRY_RUN`.
+- Hook commands receive the following env vars: `RELEASE_SCRIPT_PHASE`, `RELEASE_TAG`, `RELEASE_VERSION`, `RELEASE_STAGE`, `RELEASE_COMPONENT`, and `RELEASE_DRY_RUN`.
 
 #### Docker Compose settings
 
@@ -268,32 +280,32 @@ The following environment variable enables debugging output.
 
 ### Usage examples
 
-You can include or exclude tasks by tags in your `pyproject.toml`
+By default, `tasks()` exposes the common task set. You can still include or exclude tags in your `pyproject.toml` when needed.
 
 #### Minimal setup
 
 ```toml
 [project]
 name = "simple-cli-tool"
-version = "0.0.1"
-dependencies = ["common-python-tasks==0.0.1"]
+version = "0.1.0"
+dependencies = ["common-python-tasks==0.1.0"]
 
 [tool.poe]
-include_script = "common_python_tasks:tasks(include_tags=['format', 'lint'])"
+include_script = "common_python_tasks:tasks()"
 ```
 
-Available tasks: `format`, `lint`.
+Available tasks: common defaults such as `format`, `lint`, `test`, and `build`.
 
 #### Container-based project
 
 ```toml
 [project]
 name = "containerized-app"
-version = "0.0.1"
-dependencies = ["common-python-tasks==0.0.1"]
+version = "0.1.0"
+dependencies = ["common-python-tasks==0.1.0"]
 
 [tool.poe]
-include_script = "common_python_tasks:tasks(include_tags=['format', 'lint', 'test', 'containers'])"
+include_script = "common_python_tasks:tasks(include_tags=['common', 'containers'])"
 
 [tool.poe.env]
 DOCKERHUB_USERNAME = "myusername"
@@ -307,11 +319,11 @@ Available tasks: All tasks including `build-image` and `push-image`.
 ```toml
 [project]
 name = "custom-test-setup"
-dependencies = ["common-python-tasks==0.0.1"]
+dependencies = ["common-python-tasks==0.1.0"]
 dynamic = ["version"]
 
 [tool.poe]
-include_script = "common_python_tasks:tasks(include_tags=['test'])"
+include_script = "common_python_tasks:tasks()"
 
 [tool.pytest.ini_options]
 testpaths = ["tests", "integration"]
@@ -324,7 +336,7 @@ The `test` task will automatically use your `[tool.pytest.ini_options]` configur
 
 ### Tasks not showing up with `poe --help`
 
-Check your `[tool.poe]` configuration in `pyproject.toml`. Make sure you're using `include_script`, not `includes`.
+Check your `[tool.poe]` configuration in `pyproject.toml`. Make sure you're using `include_script`.
 
 ```toml
 # Correct
@@ -408,8 +420,9 @@ The standard Python Dockerfile incorporates several intentional design choices.
 
 ## Notes
 
-- This project dogfoods itself - it uses `common-python-tasks` for its own development
-- `RELEASE_PRE_SCRIPT` and `RELEASE_POST_SCRIPT` hooks may not be necessary for most users, as this package promotes the use of `poetry-dynamic-versioning` and `git-cliff` to automate versioning and changelog generation based on git history. However, one advanced use case for the `RELEASE_PRE_SCRIPT` hook is to edit a file before release, such as a README that references the current stable version number. This allows you to keep the README up to date with the latest version without hardcoding it.
+- This project dogfoods itself - it uses `common-python-tasks` for its own development. **That said, you must set the environment variable `PYTHONPATH=src` when running tasks locally to ensure you are using the local version of the package instead of the installed version**
+- `RELEASE_UPDATE_CHANGELOG` is enabled by default for releases and prepends a tagged section into `CHANGELOG.md` before the release tag is created. Set it to a falsy value if you prefer to manage changelog commits yourself.
+- `RELEASE_PRE_SCRIPT` and `RELEASE_POST_SCRIPT` hooks may not be necessary for most users, as this package promotes the use of `poetry-dynamic-versioning` and `git-cliff` to automate versioning and changelog generation based on git history. One advanced use case for the `RELEASE_PRE_SCRIPT` hook is to edit another file before release, such as a README that references the current stable version number. This allows you to keep the README up to date with the latest version without hardcoding it.
 - Contributions welcome! Open an issue/discussion to discuss changes before submitting a PR. I do not claim to have all the answers, and you can help determine the future of low-code solutions for Python. I am very interested in your feedback as I don't want to work in a vacuum
 - Alpha status: Expect breaking changes between minor versions until 1.0.0
 

{common_python_tasks-0.0.3 → common_python_tasks-0.1.0}/README.md

@@ -2,6 +2,8 @@
 
 This package is a collection of (very) opinionated [Poe the Poet](https://poethepoet.natn.io/guides/packaged_tasks.html) Python tasks for common Python development workflows.
 
+Instead of writing your own tasks for formatting, linting, testing, packaging, and more, you can use these pre-built tasks that work out of the box with reasonable defaults and support configuration overrides when needed. In the past, I found myself copying and pasting the same task definitions across projects, and this package is my attempt to DRY up that workflow and provide a single source of truth for common Python development tasks. I hope you can use them too.
+
 ## Quick start
 
 ### Automated setup
@@ -9,31 +11,40 @@ This package is a collection of (very) opinionated [Poe the Poet](https://poethe
 You can add `common-python-tasks` to a new project by using the handy automated installation script.
 
 ```shell
-curl -sSL https://api.github.com/repos/ci-sourcerer/common-python-tasks/contents/scripts/add-common-python-tasks.sh | jq -r '.content' | base64 -d | TAGS_TO_INCLUDE="format lint test" sh
+curl -sSL https://api.github.com/repos/ci-sourcerer/common-python-tasks/contents/scripts/add-common-python-tasks.sh | jq -r '.content' | base64 -d | sh
+```
+
+To install a specific release, set the environment variable `COMMON_PYTHON_TASKS_VERSION`.
+
+```shell
+COMMON_PYTHON_TASKS_VERSION=0.1.0 \
+  sh -c "$(curl -sSL https://api.github.com/repos/ci-sourcerer/common-python-tasks/contents/scripts/add-common-python-tasks.sh | jq -r '.content' | base64 -d)"
 ```
 
 This will complete the following steps.
 
 1. Add the latest version of `common-python-tasks` to your `pyproject.toml` dependencies
-2. Configure Poe the Poet to include only the tasks with the specified tags
+2. Configure Poe the Poet to expose the default common task set
 3. Install the package using Poetry
 
 **Always review scripts before running them!** Even though I believe I write good software, it's best practice to verify any script you download from the Internet.
 
 ### Manual setup
 
-1. Add `common-python-tasks` to your `pyproject.toml` and configure Poe the Poet to include the desired tasks
+There's no real reason to run the automated script; I just like automating everything. You can achieve the same result by following these steps.
+
+1. Add `common-python-tasks` to your `pyproject.toml` and configure Poe the Poet
 
     ```toml
     [project]
     name = "my-awesome-project"
-    version = "0.0.2"
+    version = "0.1.0"
     dependencies = [
-        "common-python-tasks==0.0.2",  # Always pin to a specific version
+        "common-python-tasks==0.1.0",  # Always pin to a specific version
     ]
 
     [tool.poe]
-    include_script = "common_python_tasks:tasks(include_tags=['format', 'lint', 'test'])"  # Include or exclude tasks by tags
+    include_script = "common_python_tasks:tasks()"  # Uses the default `common` task set
     ```
 
 2. Install the package
@@ -57,26 +68,26 @@ Internal tasks are used by other tasks and are not meant to be run directly.
 <!-- tasks-table -->
 | Task | Description | Tags |
 | - | - | - |
-| `build` | Build the project and its containers (when `containers` tag is included) | packaging, containers |
-| `build-image` | Build the container image for this project using the Dockerfile template (and configured extensions) | containers, build |
-| `build-package` | Build the package (wheel and sdist) | packaging, build |
-| `bump-version` | Bump the project version, defaulting to an inferred semantic bump from git history | packaging |
-| `changelog` | Print the changelog for the current version based on git history | packaging, release |
-| `clean` | Clean up temporary files and directories | clean |
-| `container-shell` | Run the debug image with an interactive shell | containers, debug |
-| `db-shell` | Open a psql shell to the database container | web, containers, database |
-| `format` | Format code with autoflake, black, and isort | format |
-| `lint` | Lint Python code with autoflake, black, isort, and flake8 | lint |
-| `publish-package` | Publish the package to the PyPI server | packaging |
-| `publish-github-release` | Publish or update a GitHub Release and attach built distribution assets | packaging, release |
-| `push-image` | Push the Docker image to the container registry | containers, packaging, release |
-| `release` | Run package release flow and publish containers when `containers` tag is included. Supports optional `RELEASE_PRE_SCRIPT` and `RELEASE_POST_SCRIPT` hooks. | packaging, release |
-| `reset-db` | Reset the database by deleting the database volume | web, containers, database |
-| `run-container` | Run the Docker image as a container | containers |
-| `run-db-migrations` | Run database migrations | web, containers, database |
-| `stack-down` | Bring down the development stack for the application | web, containers |
-| `stack-up` | Bring up the development stack for the application | web, containers |
-| `test` | Run the test suite with coverage | test |
+| `test` | Run the test suite with coverage (if `pytest-cov` is installed). | common, test |
+| `clean` | Clean up temporary files and directories. | clean, common |
+| `format` | Format Python code with autoflake, black, and isort. | common, format |
+| `lint` | Lint Python code with autoflake, black, isort, and flake8. | common, lint |
+| `build-image` | Build the container image for this project using the Dockerfile template. | build, containers |
+| `run-container` | Run the Docker image as a container for this project.  By default (when `tag` is `None`) this will run the most-recently-built tag for the project's image. | containers |
+| `push-image` | Push the Docker image for this project to the container registry. | containers, packaging, release |
+| `publish-package` | Publish the package to the PyPI server. | common, packaging |
+| `publish-github-release` | Publish or update a GitHub Release for the current repository. | common, packaging, release |
+| `build-package` | Build the package (wheel and sdist). | build, common, packaging |
+| `bump-version` | Bump the project version. | common, packaging |
+| `changelog` | Print the changelog for the current version based on git history and git-cliff. | common, packaging, release |
+| `release` | Run a full release flow for package and containers. | common, containers, packaging, release |
+| `build` | Build the project and its containers. | common, containers, packaging |
+| `stack-up` | Bring up the development stack for the application. | containers, fastapi, web |
+| `stack-down` | Bring down the development stack for the application. | containers, fastapi, web |
+| `reset-db` | Reset the database by deleting the database volume. | containers, database, fastapi, web |
+| `run-db-migrations` | Run database migrations. | containers, database, fastapi, web |
+| `db-shell` | Open a psql shell to the database container. | containers, database, fastapi, web |
+| `container-shell` | Run the debug image with an interactive shell. | containers, debug |
 <!-- end-tasks-table -->
 
 ## Docker Compose Development Stacks
@@ -204,9 +215,10 @@ The following environment variables configure package and container behavior.
 - `GITHUB_RELEASE_TAG` optional tag name to publish for the GitHub Release.
 - `GITHUB_RELEASE_NAME` optional release title to use for the GitHub Release.
 - `GITHUB_RELEASE_BODY` optional release body text to use for the GitHub Release.
+- `RELEASE_UPDATE_CHANGELOG` truthy value to update `CHANGELOG.md` with `git-cliff --tag "$RELEASE_TAG" --prepend CHANGELOG.md` before the release tag is created. This is enabled by default; set it to a falsy value to disable changelog commits during release.
 - `RELEASE_PRE_SCRIPT` optional shell command to run before the release steps.
 - `RELEASE_POST_SCRIPT` optional shell command to run after the release completes.
-- Hook commands receive the following env vars: `RELEASE_TAG`, `RELEASE_VERSION`, `RELEASE_STAGE`, `RELEASE_COMPONENT`, and `RELEASE_DRY_RUN`.
+- Hook commands receive the following env vars: `RELEASE_SCRIPT_PHASE`, `RELEASE_TAG`, `RELEASE_VERSION`, `RELEASE_STAGE`, `RELEASE_COMPONENT`, and `RELEASE_DRY_RUN`.
 
 #### Docker Compose settings
 
@@ -235,32 +247,32 @@ The following environment variable enables debugging output.
 
 ### Usage examples
 
-You can include or exclude tasks by tags in your `pyproject.toml`
+By default, `tasks()` exposes the common task set. You can still include or exclude tags in your `pyproject.toml` when needed.
 
 #### Minimal setup
 
 ```toml
 [project]
 name = "simple-cli-tool"
-version = "0.0.1"
-dependencies = ["common-python-tasks==0.0.1"]
+version = "0.1.0"
+dependencies = ["common-python-tasks==0.1.0"]
 
 [tool.poe]
-include_script = "common_python_tasks:tasks(include_tags=['format', 'lint'])"
+include_script = "common_python_tasks:tasks()"
 ```
 
-Available tasks: `format`, `lint`.
+Available tasks: common defaults such as `format`, `lint`, `test`, and `build`.
 
 #### Container-based project
 
 ```toml
 [project]
 name = "containerized-app"
-version = "0.0.1"
-dependencies = ["common-python-tasks==0.0.1"]
+version = "0.1.0"
+dependencies = ["common-python-tasks==0.1.0"]
 
 [tool.poe]
-include_script = "common_python_tasks:tasks(include_tags=['format', 'lint', 'test', 'containers'])"
+include_script = "common_python_tasks:tasks(include_tags=['common', 'containers'])"
 
 [tool.poe.env]
 DOCKERHUB_USERNAME = "myusername"
@@ -274,11 +286,11 @@ Available tasks: All tasks including `build-image` and `push-image`.
 ```toml
 [project]
 name = "custom-test-setup"
-dependencies = ["common-python-tasks==0.0.1"]
+dependencies = ["common-python-tasks==0.1.0"]
 dynamic = ["version"]
 
 [tool.poe]
-include_script = "common_python_tasks:tasks(include_tags=['test'])"
+include_script = "common_python_tasks:tasks()"
 
 [tool.pytest.ini_options]
 testpaths = ["tests", "integration"]
@@ -291,7 +303,7 @@ The `test` task will automatically use your `[tool.pytest.ini_options]` configur
 
 ### Tasks not showing up with `poe --help`
 
-Check your `[tool.poe]` configuration in `pyproject.toml`. Make sure you're using `include_script`, not `includes`.
+Check your `[tool.poe]` configuration in `pyproject.toml`. Make sure you're using `include_script`.
 
 ```toml
 # Correct
@@ -375,7 +387,8 @@ The standard Python Dockerfile incorporates several intentional design choices.
 
 ## Notes
 
-- This project dogfoods itself - it uses `common-python-tasks` for its own development
-- `RELEASE_PRE_SCRIPT` and `RELEASE_POST_SCRIPT` hooks may not be necessary for most users, as this package promotes the use of `poetry-dynamic-versioning` and `git-cliff` to automate versioning and changelog generation based on git history. However, one advanced use case for the `RELEASE_PRE_SCRIPT` hook is to edit a file before release, such as a README that references the current stable version number. This allows you to keep the README up to date with the latest version without hardcoding it.
+- This project dogfoods itself - it uses `common-python-tasks` for its own development. **That said, you must set the environment variable `PYTHONPATH=src` when running tasks locally to ensure you are using the local version of the package instead of the installed version**
+- `RELEASE_UPDATE_CHANGELOG` is enabled by default for releases and prepends a tagged section into `CHANGELOG.md` before the release tag is created. Set it to a falsy value if you prefer to manage changelog commits yourself.
+- `RELEASE_PRE_SCRIPT` and `RELEASE_POST_SCRIPT` hooks may not be necessary for most users, as this package promotes the use of `poetry-dynamic-versioning` and `git-cliff` to automate versioning and changelog generation based on git history. One advanced use case for the `RELEASE_PRE_SCRIPT` hook is to edit another file before release, such as a README that references the current stable version number. This allows you to keep the README up to date with the latest version without hardcoding it.
 - Contributions welcome! Open an issue/discussion to discuss changes before submitting a PR. I do not claim to have all the answers, and you can help determine the future of low-code solutions for Python. I am very interested in your feedback as I don't want to work in a vacuum
 - Alpha status: Expect breaking changes between minor versions until 1.0.0

{common_python_tasks-0.0.3 → common_python_tasks-0.1.0}/pyproject.toml

@@ -18,10 +18,10 @@ classifiers = [
 ]
 dependencies = [
     "autoflake (>=2.3.1,<3.0.0)",
-    "black (>=25.11.0,<26.0.0)",
+    "black (>=26.3.1,<27.0.0)",
     "dunamai (>=1.25.0,<2.0.0)",
     "flake8 (>=7.3.0,<8.0.0)",
-    "isort (>=7.0.0,<8.0.0)",
+    "isort (>=8.0.1,<9.0.0)",
     "poethepoet-tasks (>=0.3.0,<0.4.0)",
     "pytest-cov (>=7.0.0,<8.0.0)",
     "pytest (>=9.0.1,<10.0.0)",
@@ -30,7 +30,7 @@ dependencies = [
     "git-cliff (>=2.12.0,<3.0.0)",
 ]
 dynamic = []
-version = "0.0.3"
+version = "0.1.0"
 
 [project.urls]
 Homepage = "http://github.com/ci-sourcerer/common-python-tasks"
@@ -38,7 +38,13 @@ Source = "http://github.com/ci-sourcerer/common-python-tasks.git"
 Issues = "http://github.com/ci-sourcerer/common-python-tasks/issues"
 
 [tool.poe]
-include_script = "common_python_tasks:tasks(exclude_tags=['fastapi', 'containers'])"
+include_script = "common_python_tasks:tasks(exclude_tags=['containers'])"
+
+[tool.poe.env]
+PYTHONPATH = "src"
+RELEASE_UPDATE_CHANGELOG = "1"
+RELEASE_PRE_SCRIPT = "RELEASE_SCRIPT_PHASE=pre python scripts/release_script.py"
+RELEASE_POST_SCRIPT = "RELEASE_SCRIPT_PHASE=post python scripts/release_script.py"
 
 [tool.poetry.requires-plugins]
 poetry-dynamic-versioning = { version = ">=1.0.0,<2.0.0", extras = ["plugin"] }

common_python_tasks-0.1.0/src/common_python_tasks/__init__.py

@@ -0,0 +1,27 @@
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from typing import Sequence
+
+from poethepoet_tasks import TaskCollection
+
+__all__ = ["TaskCollection"]
+
+
+def tasks(
+    include_tags: "Sequence[str] | None" = None,
+    exclude_tags: "Sequence[str]" = tuple(),
+) -> dict:
+    from .tasks import tasks as task_collection
+
+    if include_tags is None and not exclude_tags:
+        include_tags = ("common",)
+    elif include_tags is None:
+        include_tags = tuple()
+
+    result = task_collection(include_tags=include_tags, exclude_tags=exclude_tags)
+    globals()["tasks"] = _TASKS_ENTRYPOINT
+    return result
+
+
+_TASKS_ENTRYPOINT = tasks

common_python_tasks-0.1.0/src/common_python_tasks/__main__.py

@@ -0,0 +1,108 @@
+import importlib
+import inspect
+import os
+import re
+import sys
+
+from .tasks import tasks
+
+__all__ = ["get_available_tasks", "print_available_tasks"]
+
+
+def get_available_tasks(internal: bool = False) -> list[str]:
+    """Return available task names for this package.
+
+    Args:
+        internal: When True, include internal task names starting with '_'.
+
+    Returns:
+        A list of task names.
+    """
+    return [
+        task_name
+        for task_name in tasks()["tasks"]
+        if internal or not task_name.startswith("_")
+    ]
+
+
+def _extract_docstring_excerpt(doc: str) -> str:
+    excerpt = []
+    for line in doc.strip().splitlines():
+        if re.match(r"^(Args?|Arguments?|Parameters?):\s*$", line):
+            break
+        excerpt.append(line)
+
+    while excerpt and excerpt[-1].strip() == "":
+        excerpt.pop()
+
+    return "\n".join(excerpt)
+
+
+def _get_task_docstring(task_name: str) -> str | None:
+
+    task_config = tasks()["tasks"].get(task_name)
+    if not isinstance(task_config, dict):
+        return None
+
+    script = task_config.get("script")
+    if not isinstance(script, str) or ":" not in script:
+        return None
+
+    module_name, func_name = script.split(":", 1)
+
+    try:
+        module = importlib.import_module(module_name)
+        func = getattr(module, func_name)
+    except (ImportError, AttributeError):
+        return None
+
+    doc = inspect.getdoc(func)
+    if not doc:
+        return None
+
+    return _extract_docstring_excerpt(doc)
+
+
+def _get_task_tags(task_name: str) -> list[str] | None:
+    task_variants = getattr(tasks, "_tasks", {}).get(task_name)
+    if not task_variants:
+        return None
+
+    tags = {
+        tag
+        for variant in task_variants
+        for tag in getattr(variant, "tags", ())
+        if isinstance(tag, str) and not tag.startswith("task-")
+    }
+    return sorted(tags) or None
+
+
+def print_available_tasks(internal: bool = False, include_docs: bool = False) -> None:
+    """Print available tasks.
+
+    Args:
+        internal: Whether or not to include internal task names starting with '_'.
+        include_docs: Whether or not to include task docstrings.
+    """
+    print("\nAvailable tasks in this release:\n")
+    for task_name in get_available_tasks(internal=internal):
+        print(f" - {task_name}")
+        if include_docs:
+            doc = _get_task_docstring(task_name)
+            if doc:
+                for line in doc.splitlines():
+                    print(f"     {line}")
+                print()
+
+
+if __name__ == "__main__":
+    print(
+        "common_python_tasks is not intended to be run as a standalone script. Invoke a task via poethepoet.",
+        file=sys.stderr if len(sys.argv) > 1 else sys.stdout,
+    )
+
+    if len(sys.argv) == 1:
+        debug = os.getenv("COMMON_PYTHON_TASKS_LOG_LEVEL", "info").lower() == "debug"
+        print_available_tasks(include_docs=debug)
+    else:
+        sys.exit(1)