poe-tasks-common 0.1__py3-none-any.whl

poe_tasks_common/__init__.py

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

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/_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/_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/_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/_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/_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/_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/_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/_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/_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/_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/_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,
+)

poe_tasks_common-0.1.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,16 @@
+poe_tasks_common/__init__.py,sha256=JOrQ5ecngA_j9i1J-tdqPS2g1_wZtlv-BgeP4FzDk_A,64
+poe_tasks_common/_api.py,sha256=MnDu-FkZ52YLuHVKhWgUjhbFzZHswglxJPbgfoGAKt8,3480
+poe_tasks_common/_format.py,sha256=YKhDsg93vzepdFVRTTDhrtYOktpwFltnxERoqJqxGuU,986
+poe_tasks_common/_groups/__init__.py,sha256=t4f62IyCQHjY83UWqqCsruW-jpH82kN0qHV7BDjuVaw,933
+poe_tasks_common/_groups/_docs.py,sha256=4Qxsn_1AHv_Sl4KssdJxsBiBz3HQBnjDKTQa-mzOBJo,726
+poe_tasks_common/_groups/_env.py,sha256=8RO3hNVTF0ImyaMIQ3xefO_GTRsjZ7aeFl2_v8kH0mA,400
+poe_tasks_common/_groups/_lint.py,sha256=e5J78UE90CyuVRGpCloN1nox-nuk2WNt2DPYxlq2x0g,531
+poe_tasks_common/_groups/_security.py,sha256=iJpeUz0CUeaptcPQ0fdd7-H3adT2QqNUYuVXnNKgLx8,241
+poe_tasks_common/_groups/_setup.py,sha256=2S2_Y0VgUrgSiYH9VggaeuSllS0afHRojF1XJg9W3Yo,594
+poe_tasks_common/_groups/_test.py,sha256=bsIRMDPUrGyJjOhs-Ofj9V0AtGQQQY1BqgMc3IdFF5I,1193
+poe_tasks_common/_utilities/__init__.py,sha256=BK-zI1iZe8p56HnV8mBTIabn9qwcqak_jps0ePqzbBQ,602
+poe_tasks_common/_utilities/_browse.py,sha256=a-EP1oEIi-WZ9iaVs2frrC6nMDcPzb8qSOmG_MidPa4,1276
+poe_tasks_common/_utilities/_delete.py,sha256=Gn-pHCDlzeXYC9uLuLejBR6uvS7YAb_Luf4mBv9NQWU,1047
+poe_tasks_common-0.1.dist-info/WHEEL,sha256=WvwXFgRajeoYkfRVmDhkP4Qlqo31Mk687zIO2QQoFmw,80
+poe_tasks_common-0.1.dist-info/METADATA,sha256=tNKq8Oi3euBFUy5WO2y29Q5ZvbDeD1dwSZANIziRwWs,1304
+poe_tasks_common-0.1.dist-info/RECORD,,

poe_tasks_common-0.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.11.7
+Root-Is-Purelib: true
+Tag: py3-none-any