poe-tasks-common 0.1__tar.gz

poe_tasks_common-0.1/PKG-INFO

@@ -0,0 +1,31 @@
+Metadata-Version: 2.4
+Name: poe-tasks-common
+Version: 0.1
+Summary: An opinionated collection of common poe tasks
+Keywords: poethepoet,poe,uv,pre-commit,pip-audit,ruff,pytest,coverage,sphinx
+Author: Jonathan King
+License-Expression: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Testing
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Maintainer: Jonathan King
+Requires-Python: >=3.11
+Project-URL: Repository, https://github.com/JonKing93/poe-tasks-common
+Project-URL: Documentation, https://jonking93.github.io/poe-tasks-common
+Description-Content-Type: text/markdown
+
+# poe-tasks-common
+
+An opinionated collection of common poe tasks

poe_tasks_common-0.1/README.md

@@ -0,0 +1,3 @@
+# poe-tasks-common
+
+An opinionated collection of common poe tasks

poe_tasks_common-0.1/pyproject.toml

@@ -0,0 +1,94 @@
+[build-system]
+requires = ["uv_build >= 0.11.6, <1"]
+build-backend = "uv_build"
+
+[project]
+name = "poe-tasks-common"
+version = "0.1"
+description = "An opinionated collection of common poe tasks"
+license = "MIT"
+readme = "README.md"
+requires-python = ">=3.11"
+authors = [
+    {name = "Jonathan King" },
+]
+maintainers = [
+    {name = "Jonathan King" },
+]
+keywords = [
+    "poethepoet",
+    "poe",
+    "uv",
+    "pre-commit",
+    "pip-audit",
+    "ruff",
+    "pytest",
+    "coverage",
+    "sphinx",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Natural Language :: English",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development :: Build Tools",
+    "Topic :: Software Development :: Quality Assurance",
+    "Topic :: Software Development :: Testing",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+
+[dependency-groups]
+tooling = ["poethepoet"]
+hooks = ["pre-commit"]
+security = ["pip-audit"]
+lint = ["ruff"]
+test = ["pytest>=9", "coverage>=7.10", "pytest-cov", "pytest-issues"]
+docs = [
+    "sphinx>=8.1",
+    "furo>=2025.12",
+    "sphinx_design>=0.6",
+    "sphinx-copybutton>=0.5",
+    "sphinx-substitution-extensions>=2025.12",
+]
+
+[project.urls]
+Repository = "https://github.com/JonKing93/poe-tasks-common"
+Documentation = "https://jonking93.github.io/poe-tasks-common"
+
+
+#####
+# Dev Tool Configurations
+#####
+
+[tool.uv.build-backend]
+module-root = "src"
+
+[tool.poe]
+include_script = "poe_tasks_common:tasks"
+executor = "uv"
+
+[tool.ruff.lint]
+select = [
+    "I", # isort
+    "E", # pycodestyle
+    "F", # PyFlakes
+    "B", # flake8-bugbear
+    "UP", # pyupgrade
+    "SIM", # flake8-simplify
+    "RUF", # ruff
+    "S",  # flake8-bandit
+    "T",  # flake8-print
+]
+ignore = ["RUF022", "SIM108", "SIM300", "E501"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["S101"]
+"__init__.py" = ["F401"]
+

poe_tasks_common-0.1/src/poe_tasks_common/__init__.py

@@ -0,0 +1,3 @@
+__all__ = ["tasks"]
+
+from poe_tasks_common._api import tasks

poe_tasks_common-0.1/src/poe_tasks_common/_api.py

@@ -0,0 +1,102 @@
+"""
+Function that collects and returns the complete poe schema
+"""
+
+from __future__ import annotations
+
+from copy import deepcopy
+from typing import TYPE_CHECKING
+
+from poe_tasks_common._groups import GROUPS
+from poe_tasks_common._utilities import TASKS as UTILITIES
+
+if TYPE_CHECKING:
+    Strings = list[str] | tuple[str, ...]
+
+
+def tasks(
+    *,
+    exclude_tasks: Strings = (),
+    include_tasks: Strings = (),
+    exclude_groups: Strings = (),
+    include_groups: Strings = (),
+) -> dict:
+    """
+    Builds, filters, and exports a task schema
+    
+    tasks()
+    Builds and returns the complete task schema dict.
+
+    tasks(*, exclude_tasks)
+    tasks(*, include_tasks)
+    tasks(*, exclude_groups)
+    tasks(*, include_groups)
+    Returns a filtered schema dict. Use these options to select which tasks are
+    included in the final schema. Use `include_tasks` or `exclude_tasks` to filter
+    by specific task names. Use `include_groups` or `exclude_groups` to filter by
+    task groups. Each provided filter should be a sequence of strings. When multiple
+    filters are provided, they are have the following priority:
+
+        exclude_tasks > include_tasks > exclude_groups > include_groups
+
+    In brief, task filters take priority over group filters, and excludes have priority
+    over includes. Note that providing an "include" filter activates opt-in
+    behavior - only the included tasks are exported, all others are discarded.
+
+    Args:
+        exclude_tasks: Specific tasks that should be excluded from the schema
+        include_tasks: Specific tasks that should be included in the schema
+        exclude_groups: Task groups that should be excluded from the schema
+        include_groups: Tasks groups that should be included in the schema
+
+    Returns:
+        dict: The poe task schema
+    """
+
+    filtered_groups = _filter(
+        GROUPS, include_tasks, exclude_tasks, include_groups, exclude_groups
+    )
+    return {
+        "tasks": deepcopy(UTILITIES),
+        "groups": deepcopy(filtered_groups),
+    }
+
+
+def _filter(
+    all_groups: dict,
+    include_tasks: Strings,
+    exclude_tasks: Strings,
+    include_groups: Strings,
+    exclude_groups: Strings,
+):
+    "Additively builds a filtered group dict"
+
+    # Determine whether tasks are opt-in or opt-out.
+    # Default is opt-out. Opt-in is triggered if an inclusion group is provided
+    is_opt_out = not (include_tasks or include_groups)
+
+    # Check baseline group eligibility
+    groups = {}
+    for group_name, group in all_groups.items():
+        group_id = group_name.split("_", maxsplit=1)[1]
+        keep_group = is_opt_out or group_id in include_groups or group_name in include_groups
+        if group_id in exclude_groups or group_name in exclude_groups:
+            keep_group = False
+
+        # Determine the eligibility of tasks within the group
+        tasks = {}
+        for task_name, task in group["tasks"].items():
+            keep_task = keep_group
+            if task_name in include_tasks:
+                keep_task = True
+            if task_name in exclude_tasks:
+                keep_task = False
+
+            # Save any tasks that are eligible
+            if keep_task:
+                tasks[task_name] = task
+
+        # Only save groups that have tasks
+        if tasks:
+            groups[group_name] = {"heading": group["heading"], "tasks": tasks}
+    return groups

poe_tasks_common-0.1/src/poe_tasks_common/_format.py

@@ -0,0 +1,27 @@
+"""
+Helper functions to format parts of a poe schema
+----------
+Functions:
+    task        - Formats a task configuration
+    utilities   - Formats a collection of private utility tasks
+    group       - Formats a task group
+    _replace_underscores    - Replaces underscores with hyphens in task names
+"""
+
+
+def task(help: str, **task_config) -> dict:
+    "Formats a task configuration"
+    return {"help": help} | task_config
+
+def utilities(**tasks: dict) -> dict:
+    "Formats the schema for a collection of utility tasks"
+    tasks = _replace_underscores(tasks)
+    return {f"_{key}": task for key, task in tasks.items()}
+
+def group(heading: str, **tasks: dict) -> dict:
+    "Formats the schema for a task group"
+    return {"heading": heading, "tasks": _replace_underscores(tasks)}
+
+def _replace_underscores(tasks: dict) -> dict:
+    "Replaces underscores with hyphens in task names"
+    return {key.replace("_", "-"): task for key, task in tasks.items()}

poe_tasks_common-0.1/src/poe_tasks_common/_groups/__init__.py

@@ -0,0 +1,35 @@
+"""
+Modules that build task groups
+----------
+Each of these modules defines a particular task group, which is stored in its "GROUP"
+attribute. Then this subpackage collects all the task groups in its "GROUPS" attribute.
+----------
+Attributes:
+    GROUP       - The complete collection of task groups
+
+Modules:
+    _docs       - Documentation task group
+    _env        - Development environment task group
+    _lint       - Formatting and linting task group
+    _security   - Security testing task group
+    _setup      - First time setup task group
+    _test       - Testing task group
+"""
+
+from poe_tasks_common._groups import (
+    _docs,
+    _env,
+    _lint,
+    _security,
+    _test,
+    _setup
+)
+
+GROUPS = {
+    "100_setup": _setup.GROUP,
+    "200_env": _env.GROUP,
+    "300_security": _security.GROUP,
+    "400_lint": _lint.GROUP,
+    "500_test": _test.GROUP,
+    "600_docs": _docs.GROUP,
+}

poe_tasks_common-0.1/src/poe_tasks_common/_groups/_docs.py

@@ -0,0 +1,32 @@
+"Task group for documentation"
+
+from poe_tasks_common._format import group, task
+
+output_folder = {
+    "help": "Folder containing the built documentation",
+    "name": "_output_folder",
+    "options": ["-o", "--output"],
+    "default": "${DOCS_OUTPUT:-public}",
+}
+
+
+docs = task(
+    "Rebuilds the documentation",
+    sequence=[
+        {"ref": "_rmtree ${_output_folder}"},
+        {"cmd": "sphinx-build -qa docs ${_output_folder}"},
+    ],
+    args=[output_folder],
+)
+
+open_docs = task(
+    "Opens the built documentation in a web browser",
+    ref="_browse-index ${_output_folder}",
+    args=[output_folder],
+)
+
+GROUP = group(
+    "Documentation:",
+    docs=docs,
+    open_docs=open_docs,
+)

poe_tasks_common-0.1/src/poe_tasks_common/_groups/_env.py

@@ -0,0 +1,21 @@
+"Task group for managing the developer environment"
+
+from poe_tasks_common._format import group, task
+
+
+
+sync = task(
+    "Syncs the development environment",
+    cmd="uv sync --all-groups --all-extras",
+)
+
+upgrade = task(
+    "Syncs and upgrades the development environment",
+    ref="sync --upgrade",
+)
+
+GROUP = group(
+    "Environment:",
+    sync=sync,
+    upgrade=upgrade,
+)

poe_tasks_common-0.1/src/poe_tasks_common/_groups/_lint.py

@@ -0,0 +1,23 @@
+"Task group for linting and formatting"
+
+from poe_tasks_common._format import group, task
+
+format = task(
+    "Formats the code and its tests",
+    default_item_type="cmd",
+    sequence=[
+        "ruff format ${POE_ROOT}/src ${POE_ROOT}/tests",
+        "ruff check ${POE_ROOT}/src ${POE_ROOT}/tests --select I --fix",
+    ],
+)
+
+lint = task(
+    help="Lints the code and its tests",
+    cmd="ruff check ${POE_ROOT}/src ${POE_ROOT}/tests",
+)
+
+GROUP = group(
+    "Linting:",
+    format=format,
+    lint=lint,
+)

poe_tasks_common-0.1/src/poe_tasks_common/_groups/_security.py

@@ -0,0 +1,13 @@
+"Task group for security testing"
+
+from poe_tasks_common._format import group, task
+
+audit = task(
+    "Check package dependencies for security issues",
+    cmd="pip-audit",
+)
+
+GROUP = group(
+    "Security:",
+    audit=audit,
+)

poe_tasks_common-0.1/src/poe_tasks_common/_groups/_setup.py

@@ -0,0 +1,28 @@
+"Task group for first time setup"
+
+from poe_tasks_common._format import group, task
+
+
+install_precommit = task(
+    "Installs pre-commit",
+    default_item_type="cmd",
+    sequence=[
+        "uv tool install pre-commit --with pre-commit-uv --force-reinstall",
+        "pre-commit install",
+    ],
+)
+
+setup = task(
+    "Syncs all dependencies and installs pre-commit",
+    default_item_type="ref",
+    sequence = [
+        "sync --frozen",
+        "install-precommit",
+    ]
+)
+
+GROUP = group(
+    "Setup:",
+    setup=setup,
+    install_precommit=install_precommit,
+)

poe_tasks_common-0.1/src/poe_tasks_common/_groups/_test.py

@@ -0,0 +1,49 @@
+"Task group for testing"
+
+from poe_tasks_common._format import group, task
+
+coverage = task(
+    "Prints the coverage report for the tests",
+    cmd="coverage report",
+)
+
+tests = task(
+    "Runs the tests and requires a minimum coverage",
+    sequence=[
+        {
+            "cmd": (
+                "pytest ${POE_ROOT}/tests "
+                "--cov=${POE_ROOT}/src --cov=${POE_ROOT}/tests "
+                "--cov-fail-under=${_min-coverage} "
+                "--cov-report xml:coverage.xml"
+            )
+        },
+        {"ref": "coverage"},
+    ],
+    args=[
+        {
+            "name": "_min-coverage",
+            "help": "Minimum required test coverage percent",
+            "options": ["--min-coverage"],
+            "type": "string",
+            "default": "${MIN_COVERAGE:-100}",
+        }
+    ],
+)
+
+htmlcov = task(
+    "Builds an HTML coverage report and opens in a web browser",
+    sequence=[
+        {"ref": "_rmtree htmlcov"},
+        {"cmd": "coverage html --skip-covered"},
+        {"ref": "_browse-index htmlcov"},
+    ],
+)
+
+
+GROUP = group(
+    "Testing:",
+    tests=tests,
+    htmlcov=htmlcov,
+    coverage=coverage,
+)

poe_tasks_common-0.1/src/poe_tasks_common/_utilities/__init__.py

@@ -0,0 +1,18 @@
+"""
+Modules that build private utility tasks
+----------
+Each of these modules defines utility tasks related to a particular theme. The complete
+task collection for each module is stored in its "TASKS" attribute. Then this subpackage
+collects all these tasks in its "TASKS" attribute.
+----------
+Attributes:
+    TASKS   - The complete collection of utility tasks
+
+Modules:
+    _browse - Utility tasks for opening assets in a web browser
+    _delete - Utility tasks for deleting files
+"""
+
+from poe_tasks_common._utilities import _browse, _delete
+
+TASKS = _browse.TASKS | _delete.TASKS

poe_tasks_common-0.1/src/poe_tasks_common/_utilities/_browse.py

@@ -0,0 +1,50 @@
+"Utility group for opening files in a web browser"
+
+from poe_tasks_common._format import task, utilities
+
+browse = task(
+    "Opens a URI (file or web URL) in a web browser",
+    expr="webbrowser.open(_uri)",
+    imports=["webbrowser"],
+    args=[
+        {
+            "name": "_uri",
+            "help": "The target URI (file or web URL) to open",
+            "positional": True,
+            "required": True,
+        }
+    ],
+)
+
+browse_file = task(
+    "Opens a project file in a web browser",
+    expr="webbrowser.open( (pathlib.Path(${POE_ROOT}) / _path).as_uri() )",
+    imports=["webbrowser", "pathlib"],
+    args=[
+        {
+            "name": "_path",
+            "help": "A file path relative to the project root",
+            "positional": True,
+            "required": True,
+        }
+    ],
+)
+
+browse_index = task(
+    "Opens a project subfolder's index.html file",
+    ref="_browse-file ${_folder}/index.html",
+    args=[
+        {
+            "name": "_folder",
+            "help": "A folder path relative to the project root",
+            "positional": True,
+            "required": True,
+        }
+    ],
+)
+
+TASKS = utilities(
+    browse=browse,
+    browse_file=browse_file,
+    browse_index=browse_index,
+)

poe_tasks_common-0.1/src/poe_tasks_common/_utilities/_delete.py

@@ -0,0 +1,44 @@
+"Utility group for deleting files"
+
+from poe_tasks_common._format import task, utilities
+
+rmtree = task(
+    "Deletes a project subfolder and its contents",
+    expr=(
+        "shutil.rmtree(_folder) "
+        "if (pathlib.Path(${POE_ROOT}) / _folder).exists() "
+        "else None"
+    ),
+    imports=["shutil", "pathlib"],
+    args=[
+        {
+            "name": "_folder",
+            "help": "A folder path relative to the project root",
+            "positional": True,
+            "required": True,
+        }
+    ],
+)
+
+delete = task(
+    "Deletes a project file",
+    expr=(
+        "(pathlib.Path(${POE_ROOT}) / _file).unlink() "
+        "if (pathlib.Path(${POE_ROOT}) / _file).exists() "
+        "else None"
+    ),
+    imports=["pathlib"],
+    args=[
+        {
+            "name": "_file",
+            "help": "A file path relative to the project root",
+            "positional": True,
+            "required": True,
+        }
+    ],
+)
+
+TASKS = utilities(
+    delete=delete,
+    rmtree=rmtree,
+)