Metadata-Version: 2.4
Name: mockbuck
Version: 0.1.0
Summary: A minimal SDK that downloads and locates the MockBuck JAR.
Author: FirstEigen-Labs
License-Expression: Apache-2.0
Project-URL: Repository, https://github.com/FirstEigen-Labs/MockBuck
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# mockbuck

A minimal Python SDK that downloads the MockBuck JAR on first import and exposes
its absolute local path. Requires Python 3.11 or newer and has no runtime dependencies.

## Install and use

```bash
pip install mockbuck
```

```python
import mockbuck

print(mockbuck.get_jar_path())
```

Installing the SDK does not download the JAR. Importing `mockbuck` checks
`~/.mockbuck/jars/mockbuck-core.jar` and, if missing, creates the directory and
downloads from:

```text
https://tmplog1-pub.s3.us-east-1.amazonaws.com/databuck-engine.jar
```

The JAR is approximately 540 MiB. The first import waits for the download to
finish and prints a start message, progress every 50 MiB (including percentage
when the server provides the total size), and a completion message. Subsequent
imports reuse the cached file silently. A failed download raises a
`RuntimeError` and removes the temporary file. Network operations use a
30-second socket timeout, rather than a 30-second limit on the whole download.

Both functions return a `pathlib.Path`:

- `mockbuck.get_jar_path()` returns the absolute cache path without downloading.
- `mockbuck.ensure_jar()` downloads only if the JAR is missing and returns its path.

```python
path = mockbuck.ensure_jar()
assert path.exists()
assert path.name == "mockbuck-core.jar"
```

The SDK downloads the JAR; it does not execute Java.

## Develop and test

From the repository root:

```bash
python -m venv .venv
```

Activate with `.\.venv\Scripts\Activate.ps1` on Windows PowerShell, or
`source .venv/bin/activate` on Linux/macOS. Then run:

```bash
python -m pip install -e .
python -m unittest discover -s tests -v
```

Tests use temporary home directories and mocked downloads; they do not download
the real JAR.

## Build and publish to PyPI

### Publish from GitHub Actions

Configure a PyPI Trusted Publisher with project `mockbuck`, owner
`FirstEigen-Labs`, repository `MockBuck`, workflow `publish.yml`, and no environment
name. Then open the repository's **Actions** tab, select **Publish to PyPI**, click
**Run workflow**, choose branch **main**, and run it.

The workflow builds the distributions, checks their metadata, tests the installed
wheel, and publishes to production PyPI using Trusted Publishing. No PyPI API
token or GitHub secret is needed. Publishing runs only when manually triggered
on `main`; pushing a commit does not publish a release. Increment the version
in `pyproject.toml` before publishing a later release.

### Build and upload locally

```bash
python -m pip install --upgrade build twine
python -m build
python -m twine check dist/*
python -m twine upload dist/*
```

The build creates `dist/mockbuck-0.1.0-py3-none-any.whl` and
`dist/mockbuck-0.1.0.tar.gz`. Neither contains the JAR. The upload command publishes
to production PyPI; authenticate with your PyPI API token (username `__token__`
if prompted). Keep credentials outside the repository. Increment the version in
`pyproject.toml` and remove old distribution files from `dist` before a later release.

After uploading, install with `pip install mockbuck` in a fresh virtual environment
and run the usage example above to verify the published release.

## License

Copyright 2026 FirstEigen-Labs. The Python SDK is licensed under Apache-2.0;
see [LICENSE](LICENSE). The separately downloaded JAR retains its own licensing terms.
