pystata-x 0.1.0__tar.gz

pystata_x-0.1.0/.github/workflows/build-test.yml

@@ -0,0 +1,89 @@
+name: Build & Test
+
+on:
+  push:
+    branches:
+      - '*'
+      - '**'
+  pull_request:
+    branches:
+      - main
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    name: Test (py${{ matrix.python-version }}, ${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python-version: ["3.11", "3.12", "3.13", "3.14"]
+      fail-fast: false
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+          cache-dependency-glob: "**/uv.lock"
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          uv sync --python ${{ matrix.python-version }} --all-extras --dev
+        timeout-minutes: 10
+
+      - name: Run tests that don't require Stata
+        run: |
+          uv run pytest -v -m "not requires_stata"
+        timeout-minutes: 15
+
+      - name: Build package
+        run: |
+          uv build
+        timeout-minutes: 5
+
+      - name: Test installation in clean environment
+        shell: bash
+        run: |
+          # Create fresh venv using the uv-managed Python
+          uv run python -m venv test_venv
+
+          # Activate and install
+          if [[ "$RUNNER_OS" == "Windows" ]]; then
+            source test_venv/Scripts/activate
+          else
+            source test_venv/bin/activate
+          fi
+
+          # Install built wheel
+          pip install dist/*.whl
+
+          # Test critical imports and version
+          python -c "
+          import pystata_x
+          print(f'[OK] Import successful (v{pystata_x.__version__})')
+          assert pystata_x.__version__ == '0.1.0', f'Version mismatch: {pystata_x.__version__}'
+          "
+        timeout-minutes: 10
+
+      - name: Upload build artifacts
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: build-artifacts-${{ matrix.os }}-py${{ matrix.python-version }}
+          path: |
+            dist/
+            *.log
+          retention-days: 7

pystata_x-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,40 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+    inputs:
+      ref:
+        description: "Tag or branch to publish"
+        required: true
+        default: "main"
+
+jobs:
+  build-and-publish:
+    name: Build and publish to PyPI
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/pystata-x
+    permissions:
+      id-token: write  # required for OIDC trusted publishing
+      contents: read
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+          cache-dependency-glob: "**/uv.lock"
+
+      - name: Set up Python
+        run: uv python install 3.14
+
+      - name: Build distributions
+        run: uv build
+
+      - name: Publish package distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

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

@@ -0,0 +1,72 @@
+name: Release
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'src/**'
+  workflow_dispatch:
+
+permissions:
+  actions: write
+  contents: write
+  issues: write
+  pull-requests: write
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  release:
+    name: Release
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+          cache-dependency-glob: "**/uv.lock"
+
+      - name: Set up Python
+        run: uv python install 3.14
+
+      - name: Install Hatch (version tooling)
+        run: uv tool install hatch
+
+      - name: Install release dependencies
+        run: |
+          uv sync --python 3.14 --all-extras --dev
+
+      - name: Sync versions across repo
+        run: |
+          uv run python scripts/maintenance/sync_version.py
+        timeout-minutes: 2
+
+      - name: Run tests that don't require Stata
+        run: uv run pytest -v -m "not requires_stata"
+
+      - name: Build package
+        run: uv build
+
+      - name: Release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: uv run semantic-release version
+
+      - name: Trigger PyPI publish
+        uses: actions/github-script@v7
+        with:
+          script: |
+            await github.rest.actions.createWorkflowDispatch({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              workflow_id: "publish.yml",
+              ref: context.ref
+            })

pystata_x-0.1.0/.gitignore

@@ -0,0 +1,20 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# Proprietary StataCorp pystata reference — not for redistribution
+vendor/
+
+# Workspace files
+*.log
+.DS_Store
+
+# Pi agent state
+.pi/

pystata_x-0.1.0/.python-version

@@ -0,0 +1 @@
+3.14

pystata_x-0.1.0/CHANGELOG.md

@@ -0,0 +1,17 @@
+# CHANGELOG
+
+<!-- version list -->
+
+## v0.1.0 (beta)
+
+Initial release of pystata-x — a fast, independent drop-in replacement for StataCorp's pystata.
+
+### Features
+
+- **Fast command execution**: Direct `StataSO_Execute()` calls bypass the polling-thread bottleneck, delivering ~10,000–20,000× speedup on short commands.
+- **Optimised cold initialisation**: Skips IPython probe, preference-file I/O, Python 2 compat setup, and extraneous wrapper overhead — ~11× faster than the original `stata_setup`.
+- **Vendor-compatible `run()`**: Drop-in for `pystata.run()` with identical signature and behaviour.
+- **`execute()` (fast path)**: Returns `(output, rc)` tuple — not in the vendor API.
+- **`config` module**: Init, status, and settings — mirrors the vendor's `pystata.config`.
+- **Cross-platform**: Shared-library discovery for macOS, Linux, and Windows.
+- **`track_graphs` support**: Bundled graph queries for Stata graphs.

pystata_x-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,148 @@
+# Contributing to pystata-x
+
+Thank you for your interest in contributing to pystata-x! This guide will help you set up your development environment, run tests, and understand the project structure.
+
+## Table of Contents
+
+- [Development Setup](#development-setup)
+- [Building the Project](#building-the-project)
+- [Testing](#testing)
+- [Submitting Changes](#submitting-changes)
+
+## Development Setup
+
+### Prerequisites
+
+- **Stata 17+** (Required for integration tests)
+- **Python 3.11+**
+- **uv** (Recommended) or pip
+
+### Installation
+
+1. Clone the repository:
+   ```bash
+   git clone https://github.com/tmonk/pystata-x.git
+   cd pystata-x
+   ```
+
+2. Install dependencies with uv:
+   ```bash
+   uv sync --dev
+   ```
+
+   Or with pip:
+   ```bash
+   pip install -e .[dev]
+   ```
+
+## Building the Project
+
+The project uses **hatchling** as the Python build backend. To build wheels:
+
+```bash
+uv build
+```
+
+Or using the build module directly:
+
+```bash
+python -m build
+```
+
+## Testing
+
+The test suite is organised with pytest markers.
+
+### All Tests (Requires Stata)
+
+```bash
+uv run pytest
+```
+
+### Tests Without Stata (Fast/CI)
+
+```bash
+uv run pytest -v -m "not requires_stata"
+```
+
+### Test Coverage
+
+Generate a coverage report:
+
+```bash
+uv run pytest --cov=pystata_x --cov-report=term-missing
+```
+
+Or generate an HTML report:
+
+```bash
+uv run pytest --cov=pystata_x --cov-report=html
+open htmlcov/index.html  # View the report
+```
+
+### Writing Tests
+
+When adding new tests:
+
+1. **Mark Stata-dependent tests**:
+   ```python
+   import pytest
+
+   # At module level for all tests
+   pytestmark = pytest.mark.requires_stata
+
+   # Or for individual tests
+   @pytest.mark.requires_stata
+   def test_my_stata_feature():
+       pass
+   ```
+
+2. **Mark slow tests**:
+   ```python
+   @pytest.mark.slow
+   def test_expensive_operation():
+       pass
+   ```
+
+## Submitting Changes
+
+### Pull Request Process
+
+1. **Create a feature branch**:
+   ```bash
+   git checkout -b feature/my-feature
+   ```
+
+2. **Develop and Test**:
+   - Add tests in `tests/`.
+   - Ensure `pytest -v -m "not requires_stata"` passes.
+
+3. **Commit with clear messages**:
+   Follow conventional commits (`feat:`, `fix:`, `docs:`, `chore:`, `refactor:`, `perf:`, `test:`).
+
+4. **Push and create a pull request**:
+   ```bash
+   git push origin feature/my-feature
+   ```
+
+### CI/CD
+
+GitHub Actions automatically runs on all PRs:
+- Runs all non-Stata tests (`pytest -v -m "not requires_stata"`)
+- Tests on Ubuntu with Python 3.11–3.14
+- Builds the package and tests entry points
+
+## Project Structure
+
+- `src/pystata_x/`: Python source code.
+- `tests/`: Test suite.
+- `scripts/`: Utilities for benchmarks and version syncing.
+
+## Getting Help
+
+- **Issues**: [GitHub Issues](https://github.com/tmonk/pystata-x/issues)
+- **Author**: [Thomas Monk](https://tdmonk.com)
+
+## License
+
+By contributing to pystata-x, you agree that your contributions will be licensed under the GNU Affero General Public License v3.0.