lib-detect-testenv 2.0.8__tar.gz → 3.0.1__tar.gz

lib_detect_testenv-3.0.1/.devcontainer/devcontainer.json

@@ -0,0 +1,22 @@
+{
+  "image": "mcr.microsoft.com/devcontainers/python:3.13",
+
+  "postCreateCommand": "bash -lc '\nPY=/usr/local/bin/python;\n$PY -m pip install -U pip && \\\n$PY -m pip install ipykernel && \\\n$PY -m pip install -e . && \\\n# register kernel using this exact interpreter\n$PY -m ipykernel install --name=python3 --display-name=\"Python 3 (3.13)\" --user && \\\n# patch the notebook to point to the python3 kernelspec (VS Code will bind to /usr/local/bin/python)\n$PY - <<\"PY\"\nimport json, pathlib\np = pathlib.Path(\"notebooks/Quickstart.ipynb\")\nif p.exists():\n    nb = json.loads(p.read_text(encoding=\"utf-8\"))\n    md = nb.setdefault(\"metadata\", {})\n    md[\"kernelspec\"] = {\n        \"name\": \"python3\",\n        \"display_name\": \"Python 3 (3.13)\",\n        \"language\": \"python\"\n    }\n    md[\"language_info\"] = {\"name\": \"python\"}\n    p.write_text(json.dumps(nb, ensure_ascii=False, indent=1), encoding=\"utf-8\")\n    print(\"Pinned kernelspec to python3 in\", p)\nelse:\n    print(\"Notebook not found:\", p)\nPY'\n",
+
+  "customizations": {
+    "vscode": {
+      "extensions": ["ms-toolsai.jupyter", "ms-python.python"],
+      "settings": {
+        "workbench.startupEditor": "none",
+        "jupyter.alwaysTrustNotebooks": true,
+        "jupyter.kernelPickerType": "OnlyRecommended",
+        "python.defaultInterpreterPath": "/usr/local/bin/python"
+      }
+    },
+    "codespaces": {
+      "openFiles": ["README.md"]
+    }
+  },
+
+  "postAttachCommand": "bash -lc 'if [ -f notebooks/Quickstart.ipynb ]; then code -r notebooks/Quickstart.ipynb; fi'"
+}

lib_detect_testenv-3.0.1/.devcontainer/settings.json

@@ -0,0 +1,6 @@
+{
+  "python.defaultInterpreterPath": "/usr/local/bin/python3.13",
+  "jupyter.alwaysTrustNotebooks": true,
+  "jupyter.kernelPickerType": "OnlyRecommended",
+  "jupyter.askForKernelRestart": false
+}

lib_detect_testenv-3.0.1/.env.example

@@ -0,0 +1,11 @@
+# Copy to .env and fill values as needed.
+
+# Codecov upload token (required for private repos; optional for public repos)
+CODECOV_TOKEN=
+
+# PyPI API token for release workflow (.github/workflows/release.yml)
+# Format: pypi-AgENdGVzdC5weXBpLm9yZwIk...
+PYPI_API_TOKEN=
+
+# Optional: GitHub token for API-limited tasks
+GITHUB_TOKEN=

lib_detect_testenv-3.0.1/.github/dependabot.yml

@@ -0,0 +1,22 @@
+version: 2
+updates:
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    allow:
+      - dependency-type: "direct"
+    labels:
+      - "dependencies"
+    commit-message:
+      prefix: "deps"
+      include: "scope"
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    labels:
+      - "dependencies"
+    commit-message:
+      prefix: "deps"
+      include: "scope"

lib_detect_testenv-3.0.1/.github/workflows/ci.yml

@@ -0,0 +1,200 @@
+name: CI
+
+on:
+  push:
+    branches: [ main, master ]
+  pull_request:
+    branches: [ main, master ]
+  schedule:
+    # Run daily at 3:17 AM UTC (off-peak hours, odd minute to avoid congestion)
+    - cron: '17 3 * * *'
+
+jobs:
+  test:
+    name: Tests (Python ${{ matrix.python }}, ${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        # Test against Python 3.13 and the latest 3.x available on Actions runners
+        python: ["3.13", "3.x"]
+    env:
+      PYO3_USE_ABI3_FORWARD_COMPATIBILITY: "1"
+      PYTHONIOENCODING: "utf-8"
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python }}
+          cache: 'pip'
+          cache-dependency-path: 'pyproject.toml'
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+      - name: Extract project metadata
+        shell: python
+        run: |
+          import os
+          import tomllib
+          from pathlib import Path
+
+          data = tomllib.loads(Path('pyproject.toml').read_text('utf-8'))
+          project = data['project']['name']
+          module = project.replace('-', '_')
+          dash = project.replace('_', '-')
+          scripts = list(data['project'].get('scripts', {}).keys())
+          cli_bin = scripts[0] if scripts else dash
+
+          with open(os.environ['GITHUB_ENV'], 'a', encoding='utf-8') as env:
+              env.write(f"PROJECT_NAME={project}\n")
+              env.write(f"PACKAGE_MODULE={module}\n")
+              env.write(f"CLI_BIN={cli_bin}\n")
+      - name: Install make on Windows
+        if: runner.os == 'Windows'
+        shell: pwsh
+        run: |
+          choco install -y make
+          echo "C:\\ProgramData\\chocolatey\\bin" >> $env:GITHUB_PATH
+      - name: Install journald prerequisites
+        if: runner.os == 'Linux'
+        shell: bash
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y python3-systemd
+
+      - name: Upgrade pip
+        shell: bash
+        run: python -m pip install --upgrade pip
+
+      - name: Install dev deps
+        shell: bash
+        run: |
+          uv pip install -e .[dev] --system
+
+      - name: Install Windows Event Log prerequisites
+        if: runner.os == 'Windows'
+        shell: bash
+        run: |
+          uv pip install pywin32 --system
+      - name: Cache ruff
+        uses: actions/cache@v5
+        with:
+          path: .ruff_cache
+          key: ruff-${{ runner.os }}-${{ github.sha }}
+          restore-keys: |
+            ruff-${{ runner.os }}-
+      - name: Cache pyright
+        uses: actions/cache@v5
+        with:
+          path: .pyright
+          key: pyright-${{ runner.os }}-py${{ matrix.python }}-${{ github.sha }}
+          restore-keys: |
+            pyright-${{ runner.os }}-py${{ matrix.python }}-
+            pyright-${{ runner.os }}-
+      - name: Run full test suite (lint, types, tests, coverage, codecov)
+        shell: bash
+        env:
+          TEST_VERBOSE: "1"
+        run: make test
+      - name: Build wheel/sdist
+        shell: bash
+        run: python -m build
+      - name: Verify wheel install in clean env
+        shell: bash
+        run: |
+          python -m venv .venv_wheel
+          . .venv_wheel/bin/activate 2>/dev/null || . .venv_wheel/Scripts/activate 2>/dev/null
+          pip install dist/*.whl
+          "$CLI_BIN" --version 2>/dev/null || python -m "$PACKAGE_MODULE" --version
+
+  pipx-uv:
+    name: pipx/uv verification (ubuntu)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
+          cache: 'pip'
+          cache-dependency-path: 'pyproject.toml'
+      - name: Extract project metadata
+        shell: python
+        run: |
+          import os
+          import tomllib
+          from pathlib import Path
+
+          data = tomllib.loads(Path('pyproject.toml').read_text('utf-8'))
+          project = data['project']['name']
+          module = project.replace('-', '_')
+          dash = project.replace('_', '-')
+          scripts = list(data['project'].get('scripts', {}).keys())
+          cli_bin = scripts[0] if scripts else dash
+
+          with open(os.environ['GITHUB_ENV'], 'a', encoding='utf-8') as env:
+              env.write(f"PROJECT_NAME={project}\n")
+              env.write(f"PACKAGE_MODULE={module}\n")
+              env.write(f"CLI_BIN={cli_bin}\n")
+      - name: Build wheel
+        run: |
+          python -m pip install --upgrade pip build
+          python -m build
+      - name: pipx install from wheel
+        run: |
+          python -m pip install pipx
+          pipx install dist/*.whl
+          "$CLI_BIN" --version 2>/dev/null || python -m "$PACKAGE_MODULE" --version
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+      - name: uv tool install
+        run: |
+          uv tool install .
+          "$CLI_BIN" --version 2>/dev/null || python -m "$PACKAGE_MODULE" --version
+
+  notebooks:
+    name: Execute notebooks (ubuntu, Python 3.13)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
+          cache: 'pip'
+          cache-dependency-path: 'pyproject.toml'
+      - name: Install notebook runner deps
+        run: |
+          python -m pip install --upgrade pip
+          pip install nbclient nbformat ipykernel jupyter_client
+          python -m ipykernel install --user --name python3 --display-name "Python 3"
+      - name: Execute Quickstart notebook
+        env:
+          PIP_DISABLE_PIP_VERSION_CHECK: "1"
+          PIP_NO_INPUT: "1"
+        run: |
+          python - << 'PY'
+          from pathlib import Path
+
+          import nbformat
+          from nbclient import NotebookClient
+
+          nb_path = Path('notebooks/Quickstart.ipynb')
+          if not nb_path.exists():
+              raise SystemExit(f"Notebook not found: {nb_path}")
+
+          notebook = nbformat.read(nb_path, as_version=4)
+          client = NotebookClient(
+              notebook,
+              timeout=900,
+              kernel_name='python3',
+              allow_errors=False,
+          )
+          client.execute()
+
+          out_path = Path('notebooks/Quickstart-executed.ipynb')
+          nbformat.write(notebook, out_path)
+          print(f"Executed notebook written to: {out_path}")
+          PY

lib_detect_testenv-3.0.1/.github/workflows/codeql.yml

@@ -0,0 +1,39 @@
+name: CodeQL
+
+on:
+  push:
+    branches: [ main, master ]
+  pull_request:
+    branches: [ main, master ]
+  schedule:
+    - cron: '0 8 * * 1'
+
+jobs:
+  analyze:
+    name: CodeQL Analyze
+    runs-on: ubuntu-latest
+    permissions:
+      actions: read
+      contents: read
+      security-events: write
+    strategy:
+      fail-fast: false
+      matrix:
+        language: [ 'python' ]
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@v4
+        with:
+          languages: ${{ matrix.language }}
+
+      - name: Autobuild
+        uses: github/codeql-action/autobuild@v4
+
+      - name: Perform CodeQL Analysis
+        uses: github/codeql-action/analyze@v4
+        with:
+          category: "/language:${{ matrix.language }}"

lib_detect_testenv-3.0.1/.github/workflows/release.yml

@@ -0,0 +1,50 @@
+name: Release
+
+on:
+  release:
+    types: [published]
+  push:
+    tags:
+      - 'v*'
+  workflow_dispatch: {}
+
+jobs:
+  build-and-publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v6
+      - name: Verify PyPI token is set
+        run: |
+          if [ -z "${{ secrets.PYPI_API_TOKEN }}" ]; then
+            echo "::error title=Missing PyPI token::Set the PYPI_API_TOKEN secret in GitHub repository settings to enable PyPI publishing on releases."
+            echo "See: https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions"
+            exit 1
+          fi
+      - uses: actions/setup-python@v6
+        with:
+          python-version: '3.13'
+          cache: 'pip'
+          cache-dependency-path: 'pyproject.toml'
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+      - name: Build artifacts
+        run: |
+          python -m pip install --upgrade pip
+          uv pip install build --system
+          python -m build
+      - name: Publish to PyPI
+        # Use the rolling major tag to get latest Twine/standards support (e.g., Core Metadata 2.4)
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.PYPI_API_TOKEN }}
+          attestations: false
+          skip-existing: true
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v6
+        with:
+          name: dist
+          path: dist/*

lib_detect_testenv-3.0.1/.gitignore

@@ -0,0 +1,181 @@
+# ====================================
+# ROTEK SPEZIFISCH: Git commands you might run once
+# git add .gitignore && git commit -m "Ignore IDE settings"
+# git push
+# git rm -r --cached .idea
+# git commit -m "Remove .idea and add to .gitignore"
+# git push
+# alternative : BE CAREFUL: overwrites remote history
+# git push origin master --force
+
+# ====================================
+# APP
+# ====================================
+website/build/
+website/.docusaurus/
+website/node_modules/
+node_modules/
+web-local-preview/
+translation_app*.log
+translation_web*.log
+tmp_github_web_pages/
+tmp_linkcheck_web_pages/
+.eslintcache
+.vitest/
+npm-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+.env.*
+!.env.example
+todo.md
+tmp_*
+.claude
+
+# ====================================
+# IDEs & Editors
+# ====================================
+# IntelliJ, PyCharm, etc.
+.idea/
+# VS Code workspace settings
+.vscode/
+*.code-workspace
+
+# ====================================
+# Python bytecode & caches
+# ====================================
+# __pycache__: compiled .pyc files at any depth
+# *.py[cod]: catches .pyc, .pyo, .pyd
+__pycache__/
+*.py[cod]
+*$py.class     # other compiled artifacts
+
+# pytest, coverage, MyPy, Hypothesis
+.pytest_cache/
+.mypy_cache/
+.pyright/
+.coverage*
+htmlcov/
+nosetests.xml
+coverage.xml
+*.cover
+.hypothesis/
+.tox/
+.nox/
+
+# general cache directories (any project-level caching)
+.cache/
+.run/
+.import_linter_cache/
+
+# ====================================
+# Build & distribution artifacts
+# ====================================
+# source/package builds
+build/
+dist/
+*.egg-info/    # metadata for pip installs
+*.egg
+*.whl
+pip-wheel-metadata/
+*.manifest     # PyInstaller metadata
+*.spec         # PyInstaller spec files
+
+# Eggs, parts, wheels, sdist, etc.
+develop-eggs/
+.eggs/
+parts/
+sdist/
+wheels/
+downloads/
+var/
+
+# pip logs & installer leftovers
+pip-log.txt
+pip-delete-this-directory.txt
+.installed.cfg
+
+# ====================================
+# Virtual environments & secrets
+# ====================================
+# common venv folder names
+env/
+venv/
+ENV/
+.venv/
+# backups, alternate names
+env.bak/
+venv.bak/
+# dotenv files with credentials
+.env
+
+# ====================================
+# Project-specific & framework files
+# ====================================
+# Django logs & local overrides
+*.log
+local_settings.py
+
+# Flask instance folder
+instance/
+.webassets-cache
+
+# Scrapy cache
+.scrapy
+
+# Sphinx docs
+docs/_build/
+
+# PyBuilder output
+target/
+
+# Jupyter notebooks checkpoints
+.ipynb_checkpoints
+
+# pyenv Python version file
+.python-version
+
+# Celery beat schedule
+celerybeat-schedule
+
+# SageMath parsed files
+*.sage.py
+
+# Spyder IDE
+.spyderproject
+.spyproject
+
+# Rope IDE
+.ropeproject
+
+# MkDocs static site folder
+/site
+
+# ====================================
+# OS-specific files
+# ====================================
+# macOS
+.DS_Store
+# Windows
+Thumbs.db
+ehthumbs.db
+
+# Archives
+*.zip
+
+# Thunderbird build artifact (created temporarily by pack script)
+sources/manifest.json
+
+# ====================================
+# Tool-specific extras
+# ====================================
+# Codecov uploader script (downloaded during local uploads)
+codecov.sh
+codecov.xml
+
+# Nix build result symlink
+result
+
+# Optional lockfiles (for alternative managers)
+poetry.lock
+pdm.lock
+uv.lock

lib_detect_testenv-3.0.1/.qlty/qlty.toml

@@ -0,0 +1,2 @@
+exclude_patterns = ["scripts/**"]
+test_patterns = ["tests/**"]

lib_detect_testenv-3.0.1/.snyk

@@ -0,0 +1,5 @@
+# Snyk (https://snyk.io) policy file
+exclude:
+ global:
+   - scripts/**
+   - tests/**

lib_detect_testenv-3.0.1/CHANGELOG.md

@@ -0,0 +1,109 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [3.0.1] - 2025-12-15
+
+### Changed
+
+- Replaced `tomllib`/`tomli` with `rtoml` for TOML parsing in scripts
+- Updated GitHub Actions dependencies:
+  - `actions/cache` v4 → v5
+  - `actions/upload-artifact` v5 → v6
+- Added `PYTHONIOENCODING: "utf-8"` environment variable to CI workflow for consistent encoding
+
+## [3.0.0] - 2025-11-04
+
+### Added
+
+**Core Library Features:**
+- `add_path_to_syspath()` function to add paths to sys.path with duplicate prevention
+- Full support for PathLike objects and string paths
+- Automatic resolution of relative paths to absolute paths
+- File path handling (adds parent directory when given a file)
+
+**CLI Detection Commands:**
+- `check` - Check if any test environment is active (pytest, doctest, setup.py test)
+- `pytest` - Check if pytest is active
+- `doctest` - Check if doctest is active
+- `setup` - Check if setup.py is active
+- `--quiet` flag for all detection commands (exit code only, no output)
+- `--arg-string` option to test custom argument strings
+- `--test-only` flag for setup command (check only "setup.py test")
+
+**CLI Utility Commands:**
+- `hello` - Demo command to print greeting message
+- `fail` - Demo command to trigger intentional failure for testing error handling
+- `info` - Display package metadata and version information
+
+**3-Level Exit Code System:**
+- Exit code **0** = Test environment detected (success)
+- Exit code **1** = No test environment detected (normal negative result)
+- Exit code **2** = Error occurred (command failed with exception)
+- Follows Unix conventions for intuitive shell scripting
+- All detection commands implement consistent exit code behavior
+
+**Comprehensive Test Suite:**
+- 68 tests total (100% passing rate)
+- 28 tests for core library functions (test_lib_detect_testenv.py)
+  - Tests for all detection functions
+  - Tests for add_path_to_syspath with edge cases
+  - Tests for PathLike support and duplicate prevention
+- 23 tests for CLI commands (test_cli.py)
+  - Tests for all detection commands
+  - Tests for exit codes
+  - Tests for quiet mode and flags
+- Full coverage of test environment detection scenarios
+
+**Documentation:**
+- Comprehensive README.md with CLI and Python API usage
+- Exit code documentation with shell scripting examples
+- Function reference with parameters, returns, and examples
+- Common usage patterns section
+- INSTALL.md updated for optional dependencies
+
+### Changed
+
+**BREAKING CHANGES:**
+- Renamed internal module `detect_testenv.py` to `lib_detect_testenv.py`
+- Minimal dependencies - Only `rich-click>=1.9.4` required for CLI functionality
+  - `dependencies = ["rich-click>=1.9.4"]` - Required for CLI entry point
+  - Core detection library functions have no external dependencies (pure stdlib)
+  - Users can import detection functions (`is_pytest_active()`, etc.) without using rich-click
+  - CLI commands require rich-click for beautiful terminal output
+
+**Configuration:**
+- Keywords updated from `["logging", "rich", "cli", "terminal", "ansi"]` to `["testing", "pytest", "doctest", "unittest", "test-detection", "test-environment"]` for accurate PyPI discoverability
+- Import linter configuration updated to check correct architecture (CLI → lib_detect_testenv → behaviors)
+- pyproject.toml restructured with optional dependency groups
+
+**Documentation:**
+- Updated README.md from RST format to Markdown with:
+  - Complete function reference documentation
+  - CLI usage examples with exit code explanations
+  - Shell scripting patterns and best practices
+  - Common usage patterns section
+- Default CLI behavior now runs `check` command when invoked without arguments
+- All CLI commands documented with examples
+
+### Fixed
+- CLI now uses actual library detection functions instead of template boilerplate
+- Import paths updated throughout codebase to reflect renamed module
+- Documentation accurately reflects actual functionality
+- All 68 tests passing with proper coverage of core functionality
+- Exit code handling consistent across all detection commands
+- Error handling improved with try/except blocks returning exit code 2
+
+### Documentation Improvements
+- Added comprehensive 3-level exit code system documentation
+- Added shell scripting examples for all detection commands
+- Documented hello/fail demo commands
+- Added comprehensive Python API reference with all function signatures
+- Exit code handling examples for different shell scripting scenarios
+- Added case statement examples for handling all three exit codes
+
+## [1.0.0] - 2025-11-04
+- Bootstrap `lib_detect_testenv`