Metadata-Version: 2.4
Name: sample_data_factory
Version: 0.8.0
Summary: Reusable test data factory for CSV and FIDE XML archives.
License-Expression: MIT
License-File: LICENSE.txt
Author: Hendrik du Toit
Author-email: hendrik@brightedge.co.za
Maintainer: Hendrik du Toit
Maintainer-email: hendrikdt@citiqprepaid.co.za
Requires-Python: >=3.10
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Archiving :: Packaging
Project-URL: Homepage, https://github.com/RealTimeEvents/sample_data_factory
Project-URL: Issues, https://github.com/RealTimeEvents/sample_data_factory/issues
Project-URL: Repository, https://github.com/RealTimeEvents/sample_data_factory.git
Project-URL: changelog, https://github.com/RealTimeEvents/sample_data_factory/releases
Description-Content-Type: text/markdown

# sample_data_factory

______________________________________________________________________

## Short description

`sample_data_factory` is a reusable Python helper for generating deterministic ZIP archives used in test flows, including URS CSV exports and FIDE players XML exports.

______________________________________________________________________

## Release Highlights

- Package metadata and import paths have been aligned to `sample_data_factory` and `sdf`.
- Archive generation now covers both URS CSV and FIDE players XML ZIP outputs through `SampleDataFactory`.
- Google Drive uploads support optional nested sub-folder creation for organized artifact output.
- Python runtime support is aligned to `>=3.10` in project configuration.

______________________________________________________________________

## Module Overview

### Key Features

- Builds URS publication ZIP archives containing CSV payloads.
- Builds FIDE players-list ZIP archives containing XML payloads.
- Supports either local byte output or upload to Google Drive.
- Can create nested Google Drive sub-folders when uploading files.
- Includes unit tests for archive generation and constructor validation.

### Project Structure

- `src/sdf/`: Core package implementation (`sample_data_factory.py`).
- `tests/unit/`: Unit tests for archive builders and helper methods.
- `scripts/`: SQL/bootstrap assets (legacy resources have been removed).
- `legacy/`: Archived resources excluded from normal test runs.
- `*.ps1`: Environment and dependency setup scripts.

______________________________________________________________________

## Getting Started

### Prerequisites

- Python 3.10+
- Poetry

### Setup

```powershell
# 1) Generate .env values from environment variables
.\SetupDotEnv.ps1

# 2) Configure private Poetry sources when required
.\SetupPrivateRepoAccess.ps1

# 3) Optional: configure GitHub CLI access
.\SetupGitHubAccess.ps1

# 4) Install and sync project dependencies
.\InstallDevEnv.ps1

# 5) Run tests
poetry run pytest
```

### Usage Example

```python
from datetime import date

from sdf.sample_data_factory import SampleDataFactory

factory = SampleDataFactory(
    data_structure={
        "headers": ["PlayerID", "PlayerName"],
        "rows": [["1", "Player One"], ["2", "Player Two"]],
    },
    drive=None,
    file_prefix="Players",
    out_file_date=date(2026, 1, 1),
    target_folder_id=None,
    sub_folder_name=None,
)

archive_bytes = factory.build_urs_rating_pub_zip()
```

### Common Commands

```powershell
poetry install
poetry run pytest
poetry run pytest --cov=src --cov=tests --cov-report=term-missing
poetry run black src tests
poetry run isort src tests
poetry run flake8 src tests
poetry run pre-commit run --all-files
```

______________________________________________________________________

## Automation Scripts

- `InstallPy.ps1`: Bootstraps Python/Poetry setup.
- `InstallDevEnv.ps1`: Installs development dependencies and pre-commit hooks.
- `SetupDotEnv.ps1`: Generates `.env` from required environment variables.
- `SetupPrivateRepoAccess.ps1`: Configures private package source credentials.
- `SetupGitHubAccess.ps1`: Configures GitHub authentication for local automation.

______________________________________________________________________

## Active Workflows

- `.github/workflows/py-temp-pr-pub-no_docker-def.yaml`: Pull request validation workflow.
- `.github/workflows/py-temp-publish-pub-build_release_notify_after_merge-def.yaml`: Post-merge release and publish workflow.

