qstatus 0.1.0__tar.gz

qstatus-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,33 @@
+One sentence explaining what this PR does.
+
+Follow this format by default, but you can deviate if that makes the PR
+clearer, for example for an unusually large PR.
+
+## Related:
+Optional. Use only if truly needed. Link related issues, docs, PRs, or
+discussion.
+- ...
+
+## Changes:
+What changed in the final state of the PR. Describe the current behavior the
+reader needs to know. Do not narrate the whole implementation history of the PR.
+Be concise.
+- ...
+- ...
+
+## Why:
+What problem this solves and why the changes were needed.
+Be concise.
+- ...
+- ...
+
+## Details:
+Optional. Use only if truly needed. Use this for important details or gotchas
+that would clutter the changes section.
+- ...
+
+## How To Try It:
+Optional. Use only if truly needed. Use this when a reviewer would benefit
+from commands, paths, task ids, or links to inspect the change directly. Do
+not repeat generic CI or test output.
+- ...

qstatus-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,137 @@
+name: Checks
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  ruff:
+    name: Ruff
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.11"
+          cache: pip
+          cache-dependency-path: pyproject.toml
+
+      - name: Install Ruff
+        run: python -m pip install ruff==0.15.9
+
+      - name: Ruff format
+        run: python -m ruff format --check --diff .
+
+      - name: Ruff lint
+        run: python -m ruff check --output-format=full .
+
+  python-checks:
+    name: Ruff + Mypy + Pytest
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+          cache-dependency-path: pyproject.toml
+
+      - name: Install Python dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e ".[dev]"
+
+      - name: Ruff format
+        run: python -m ruff format --check --diff .
+
+      - name: Ruff lint
+        run: python -m ruff check --output-format=full .
+
+      - name: Mypy static type checks
+        run: python -m mypy
+
+      - name: Pytest tests
+        run: python -m pytest
+
+  package-pip:
+    name: Package Build (pip)
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.11"
+          cache: pip
+          cache-dependency-path: pyproject.toml
+
+      - name: Install Python dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e ".[dev]"
+
+      - name: Build package
+        run: python -m build
+
+      - name: Install built wheel
+        run: python -m pip install --force-reinstall dist/*.whl
+
+      - name: Smoke test installed package
+        run: python -c "import qstatus; print(qstatus.__version__)"
+
+  package-uv:
+    name: Package Build (uv)
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+          cache-dependency-glob: uv.lock
+
+      - name: Set up Python
+        run: uv python install 3.11
+
+      - name: Install Python dependencies
+        run: uv sync --extra dev --locked
+
+      - name: Build package
+        run: uv build
+
+      - name: Install built wheel
+        run: uv pip install --force-reinstall dist/*.whl
+
+      - name: Smoke test installed package
+        run: uv run --no-sync python -c "import qstatus; print(qstatus.__version__)"

qstatus-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,36 @@
+name: Release
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  publish:
+    name: Publish to PyPI
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      contents: read
+      id-token: write
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.11"
+
+      - name: Build package
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install build
+          python -m build
+
+      - name: Publish package distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

qstatus-0.1.0/.gitignore

@@ -0,0 +1,27 @@
+__pycache__/
+*.py[cod]
+*$py.class
+
+.Python
+.venv/
+venv/
+env/
+ENV/
+
+build/
+dist/
+*.egg-info/
+.eggs/
+
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+.env
+.env.*
+
+.DS_Store
+.idea/
+.vscode/

qstatus-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,39 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.9
+    hooks:
+      - id: ruff
+      - id: ruff-format
+        args: ["--check"]
+
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: check-symlinks
+      - id: destroyed-symlinks
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-toml
+      - id: check-merge-conflict
+      - id: check-case-conflict
+      - id: check-executables-have-shebangs
+      - id: check-added-large-files
+        args: ["--maxkb=2000"]
+      - id: check-shebang-scripts-are-executable
+      - id: detect-private-key
+      - id: debug-statements
+
+  - repo: https://github.com/codespell-project/codespell
+    rev: v2.4.1
+    hooks:
+      - id: codespell
+        additional_dependencies:
+          - tomli
+
+  - repo: https://github.com/pre-commit/pygrep-hooks
+    rev: v1.10.0
+    hooks:
+      - id: rst-backticks
+      - id: rst-directive-colons
+      - id: rst-inline-touching-normal

qstatus-0.1.0/.python-version

@@ -0,0 +1 @@
+3.11

qstatus-0.1.0/AGENTS.md

@@ -0,0 +1,22 @@
+# AGENTS.md
+
+Repo-specific instructions for agents working with the `qstatus` package.
+
+## Package Conventions
+
+- Keep importable package code under `src/qstatus/`.
+- Put CLI entrypoint behavior in `src/qstatus/cli.py`.
+
+## Validation
+
+- Run checks relevant to the files changed.
+- For README/docs-only changes, run formatting and pre-commit hygiene.
+- For Python or packaging changes, also run Ruff, mypy, pytest, and build
+  checks.
+
+## Pull Requests
+
+- Use `.github/PULL_REQUEST_TEMPLATE.md` for PR descriptions.
+- Do not commit secrets, credentials, local runtime config, or scratch notes.
+- Keep `AGENTS.md` updated when recurring agent instructions become
+  repo-specific.

qstatus-0.1.0/PKG-INFO

@@ -0,0 +1,96 @@
+Metadata-Version: 2.4
+Name: qstatus
+Version: 0.1.0
+Summary: Quick local status snapshots for developer workspaces.
+Project-URL: Homepage, https://github.com/alik-git/qstatus
+Project-URL: Repository, https://github.com/alik-git/qstatus
+Project-URL: Issues, https://github.com/alik-git/qstatus/issues
+Author-email: Ali K <alikgithb@gmail.com>
+Maintainer-email: Ali K <alikgithb@gmail.com>
+Keywords: cli,developer-tools,git,status
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: mypy>=1.15; extra == 'dev'
+Requires-Dist: pre-commit>=4.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.11; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# qstatus
+
+Quick local status snapshots for developer workspaces.
+
+## Installation
+
+Recommended with `uv`:
+
+```bash
+uv sync --extra dev
+```
+
+Standard Python fallback:
+
+```bash
+python -m pip install -e ".[dev]"
+```
+
+## Usage
+
+```bash
+qstatus
+qstatus --version
+```
+
+## Development
+
+Run the standard checks before opening a PR:
+
+```bash
+uv run ruff format --check .
+uv run ruff check .
+uv run mypy
+uv run pytest
+uv build
+```
+
+If you are using standard Python tools instead of uv:
+
+```bash
+python -m ruff format --check .
+python -m ruff check .
+python -m mypy
+python -m pytest
+python -m build
+```
+
+## Publishing
+
+This repo publishes to PyPI through GitHub Actions Trusted Publishing. The
+release workflow is [`.github/workflows/release.yml`](.github/workflows/release.yml).
+
+Use these values in PyPI's pending trusted publisher form:
+
+```text
+PyPI project name: qstatus
+Owner: alik-git
+Repository name: qstatus
+Workflow name: release.yml
+Environment name: pypi
+```
+
+The workflow filename is `release.yml`; the display name inside that file is
+`Release`, but PyPI wants the filename. The `pypi` environment should also exist
+under the GitHub repository's environment settings.
+
+Publishing is release-driven: normal pushes and pull requests build and test the
+package, but publishing happens when a GitHub Release is published or the release
+workflow is manually dispatched.

qstatus-0.1.0/README.md

@@ -0,0 +1,69 @@
+# qstatus
+
+Quick local status snapshots for developer workspaces.
+
+## Installation
+
+Recommended with `uv`:
+
+```bash
+uv sync --extra dev
+```
+
+Standard Python fallback:
+
+```bash
+python -m pip install -e ".[dev]"
+```
+
+## Usage
+
+```bash
+qstatus
+qstatus --version
+```
+
+## Development
+
+Run the standard checks before opening a PR:
+
+```bash
+uv run ruff format --check .
+uv run ruff check .
+uv run mypy
+uv run pytest
+uv build
+```
+
+If you are using standard Python tools instead of uv:
+
+```bash
+python -m ruff format --check .
+python -m ruff check .
+python -m mypy
+python -m pytest
+python -m build
+```
+
+## Publishing
+
+This repo publishes to PyPI through GitHub Actions Trusted Publishing. The
+release workflow is [`.github/workflows/release.yml`](.github/workflows/release.yml).
+
+Use these values in PyPI's pending trusted publisher form:
+
+```text
+PyPI project name: qstatus
+Owner: alik-git
+Repository name: qstatus
+Workflow name: release.yml
+Environment name: pypi
+```
+
+The workflow filename is `release.yml`; the display name inside that file is
+`Release`, but PyPI wants the filename. The `pypi` environment should also exist
+under the GitHub repository's environment settings.
+
+Publishing is release-driven: normal pushes and pull requests build and test the
+package, but publishing happens when a GitHub Release is published or the release
+workflow is manually dispatched.

qstatus-0.1.0/docs/api.md

@@ -0,0 +1,15 @@
+# API
+
+`qstatus` currently exposes package metadata and a small CLI entry point.
+
+```python
+import qstatus
+
+print(qstatus.__version__)
+```
+
+The command-line entry point is:
+
+```bash
+qstatus
+```

qstatus-0.1.0/docs/ci-private-submodules.md

@@ -0,0 +1,67 @@
+# CI Private Submodules
+
+If a package created from this template uses private GitHub submodules, the
+default [`GITHUB_TOKEN`](https://docs.github.com/en/actions/security-for-github-actions/security-guides/automatic-token-authentication)
+may not be able to clone them in GitHub Actions.
+
+Use a [GitHub App](https://docs.github.com/en/apps/overview) token pattern for
+private submodules. The
+[`actions/create-github-app-token`](https://github.com/actions/create-github-app-token)
+action creates a short-lived installation access token that can be scoped to the
+parent repo and the private submodule repos:
+
+```yaml
+- name: Create GitHub App token
+  id: app-token
+  uses: actions/create-github-app-token@v3
+  with:
+    client-id: ${{ vars.CI_APP_CLIENT_ID }}
+    private-key: ${{ secrets.CI_APP_PRIVATE_KEY }}
+    owner: your-org
+    repositories: |
+      your_repo
+      private_submodule_repo
+    permission-contents: read
+
+- name: Check out repository
+  uses: actions/checkout@v6
+  with:
+    token: ${{ steps.app-token.outputs.token }}
+    submodules: recursive
+    persist-credentials: false
+```
+
+Required repository settings:
+
+- Variable: `CI_APP_CLIENT_ID`
+- Secret: `CI_APP_PRIVATE_KEY`
+
+Create these under the repository's
+[Actions variables and secrets settings](https://docs.github.com/en/actions/how-tos/write-workflows/choose-what-workflows-do/use-variables)
+and
+[Actions secrets settings](https://docs.github.com/en/actions/how-tos/security-for-github-actions/security-guides/using-secrets-in-github-actions).
+
+The GitHub App must be installed on the parent repo and each private submodule
+repo listed under `repositories`. See GitHub's docs for
+[installing your own GitHub App](https://docs.github.com/en/apps/using-github-apps/installing-your-own-github-app).
+
+Replace the variable and secret names in the YAML with whatever naming
+convention your repository uses.
+
+`actions/create-github-app-token` still accepts the older `app-id` input, but
+the upstream action now recommends `client-id`. Prefer `client-id` in new
+workflows to avoid deprecation/legacy-input warnings. GitHub documents where to
+find a GitHub App's client ID in the
+[GitHub App settings](https://docs.github.com/en/apps/maintaining-github-apps/modifying-a-github-app).
+
+Symptoms when this is missing:
+
+- PR checks stay queued and then fail during checkout.
+- [`actions/checkout`](https://github.com/actions/checkout) reports that it
+  cannot clone a private submodule.
+- SSH submodule URLs like `git@github.com:org/private_repo.git` fail in CI even
+  though they work locally.
+
+When adapting the template, either avoid private submodules in CI or add the
+token step before every `actions/checkout` step that uses `submodules:
+recursive`.

qstatus-0.1.0/pyproject.toml

@@ -0,0 +1,149 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[project]
+name = "qstatus"
+version = "0.1.0"
+description = "Quick local status snapshots for developer workspaces."
+readme = "README.md"
+requires-python = ">=3.11"
+authors = [
+  { name = "Ali K", email = "alikgithb@gmail.com" },
+]
+maintainers = [
+  { name = "Ali K", email = "alikgithb@gmail.com" },
+]
+keywords = ["cli", "developer-tools", "git", "status"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Typing :: Typed",
+]
+dependencies = []
+
+[project.optional-dependencies]
+dev = [
+  "build>=1.2",
+  "mypy>=1.15",
+  "pre-commit>=4.0",
+  "pytest>=8.0",
+  "ruff>=0.11",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/qstatus"]
+
+[project.scripts]
+qstatus = "qstatus.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/alik-git/qstatus"
+Repository = "https://github.com/alik-git/qstatus"
+Issues = "https://github.com/alik-git/qstatus/issues"
+
+[tool.ruff]
+line-length = 88
+target-version = "py311"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+# This template uses a fairly strict Ruff setup by default. The less universal
+# rule families are marked below; comment them out if they are too noisy for a
+# new project.
+extend-select = [
+  # Core Python style and modernization.
+  "E",       # pycodestyle errors
+  "W",       # pycodestyle warnings
+  "I",       # import sorting
+  "UP",      # Python modernization
+  # Bug-risk checks.
+  "B",       # flake8-bugbear bug patterns
+  "BLE",     # blind except / bare except
+  "PLE",     # pylint errors
+  "PLW",     # pylint warnings
+  "S",       # Bandit security checks; comment out if too noisy.
+  # Maintainability checks.
+  "A",       # flake8-builtins: avoid shadowing id/list/input/etc.
+  "ARG",     # unused function arguments
+  "C4",      # cleaner comprehensions
+  "DTZ",     # timezone-aware datetimes
+  "FBT003",  # boolean positional values in function calls
+  "NPY",     # NumPy-specific checks
+  "PERF",    # performance footguns
+  "PTH",     # prefer pathlib over os.path
+  "RET",     # return control-flow simplification
+  "SIM",     # flake8-simplify
+  # Logging and import hygiene.
+  "G",       # logging format strings
+  "LOG",     # logging anti-patterns
+  "TC",      # type-checking import hygiene
+  # Strict docs/annotations/tests. Comment these out for a looser template.
+  "ANN201",  # public function return annotations
+  "ANN202",  # private function return annotations
+  "ANN204",  # special-method return annotations
+  "D100",    # module docstrings
+  "D104",    # package docstrings
+  "D102",    # public method docstrings
+  "D103",    # public function docstrings
+  "D2",      # docstring whitespace/placement conventions
+  "D4",      # docstring content conventions
+  "PT",      # pytest style
+  # Ruff suppression hygiene and narrow style correctness rules.
+  "RUF100",  # unused noqa
+  "RUF102",  # invalid noqa rule code
+  "RUF104",  # unmatched ruff suppression comments
+  "PLR0402", # prefer from-module imports for aliased submodule imports
+  "PLR1722", # prefer sys.exit() over the interactive exit() helper
+  "TRY203",  # useless try/except blocks that immediately re-raise
+]
+
+ignore = [
+  # typing.cast(SomeType, value) is clearer than quoted type names.
+  "TC006",
+]
+
+[tool.ruff.lint.per-file-ignores]
+# Do not flag assert statements in tests.
+"tests/**/*.py" = ["S101"]
+
+[tool.ruff.lint.isort]
+known-first-party = ["qstatus"]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.ruff.format]
+docstring-code-format = true
+
+[tool.mypy]
+python_version = "3.11"
+files = ["src/qstatus"]
+
+# Type-check function bodies even before every function is fully annotated.
+check_untyped_defs = true
+no_implicit_optional = true
+strict_equality = true
+
+# High-signal warnings without full mypy strict mode.
+warn_redundant_casts = true
+warn_return_any = true
+warn_unreachable = true
+warn_unused_configs = true
+warn_unused_ignores = true
+
+# Missing packages still fail as import-not-found. This only suppresses the
+# weaker "installed but has no stubs/py.typed marker" error for third-party
+# packages.
+ignore_missing_imports = false
+follow_imports = "silent"
+disable_error_code = ["import-untyped"]
+
+# Make local and CI output easier to read and easier to suppress precisely.
+show_error_codes = true
+pretty = true