# AdaptsAPI Client
A Python client library and CLI for the Adapts API, designed for triggering documentation generation via API Gateway → SNS.
[](https://badge.fury.io/py/adaptsapi)
[](https://www.python.org/downloads/)
[](LICENSE)
[](https://github.com/adaptsai/adaptsapi)
## Features
- 🚀 **Simple Python Client** for making API calls to Adapts services
- 🔑 **Secure token management** with environment variables or local config
- 📄 **Flexible payload support** via JSON files or inline data
- 🔧 **Configurable endpoints** with default endpoint support
- ✅ **Built-in payload validation** for documentation generation requests
- 🧪 **Comprehensive test suite** with 98% code coverage
- 🤖 **GitHub Actions integration** for automated wiki documentation
- 📦 **CLI tool** for command-line usage
## Installation
### From PyPI
```bash
pip install adaptsapi
```
### From Source
```bash
git clone https://github.com/adaptsai/adaptsapi.git
cd adaptsapi
pip install -e .
```
## Quick Start
### 1. Set up your API token
You can provide your API token in three ways (in order of precedence):
1. **Environment variable** (recommended for CI/CD):
```bash
export ADAPTS_API_KEY="your-api-token-here"
```
2. **Local config file** (`config.json` in current directory):
```json
{
"token": "your-api-token-here",
"endpoint": "https://your-api-endpoint.com/prod/generate_wiki_docs"
}
```
3. **Interactive prompt** (first-time setup):
```bash
adaptsapi --data '{"test": "payload"}'
# CLI will prompt for token and save to config.json
```
### 2. Using the Python Client
```python
from adaptsapi.generate_docs import post, PayloadValidationError
# Create your payload
payload = {
"email_address": "user@example.com",
"user_name": "john_doe",
"repo_object": {
"repository_name": "my-repo",
"source": "github",
"repository_url": "https://github.com/user/my-repo",
"branch": "main",
"size": "12345",
"language": "python",
"is_private": False,
"git_provider_type": "github",
"refresh_token": "github_token_here"
}
}
# Make the API call
try:
response = post(
"https://api.adapts.ai/prod/generate_wiki_docs",
"your-api-token",
payload
)
response.raise_for_status()
result = response.json()
print("✅ Success:", result)
except PayloadValidationError as e:
print(f"❌ Validation error: {e}")
except Exception as e:
print(f"❌ API error: {e}")
```
### 3. Using the CLI
**Using inline JSON data:**
```bash
adaptsapi \
--endpoint "https://api.adapts.ai/prod/generate_wiki_docs" \
--data '{"email_address": "user@example.com", "user_name": "john_doe", "repo_object": {...}}'
```
**Using a JSON payload file:**
```bash
adaptsapi \
--endpoint "https://api.adapts.ai/prod/generate_wiki_docs" \
--payload-file payload.json
```
## Testing
The library includes a comprehensive test suite with 98% code coverage.
### Running Tests
#### Quick Test Run
```bash
# Run all tests
python -m pytest
# Run with verbose output
python -m pytest -v
# Run specific test file
python -m pytest tests/test_generate_docs.py
# Run with coverage report
python -m pytest --cov=src/adaptsapi --cov-report=html
```
#### Using the Test Runner
```bash
# Run unit tests only (fast, no external dependencies)
python run_tests.py --type unit
# Run integration tests (requires API key)
python run_tests.py --type integration
# Run all tests with coverage
python run_tests.py --type coverage
# Run with custom API key
python run_tests.py --type integration --api-key "your-api-key"
```
#### Test Categories
- **Unit Tests**: Fast tests that mock external dependencies
- **Integration Tests**: Tests that make real API calls (marked with `@pytest.mark.integration`)
- **CLI Tests**: Tests for command-line interface functionality
- **Config Tests**: Tests for configuration management
### Test Coverage
The test suite covers:
- ✅ **Payload Validation**: All validation logic and error cases
- ✅ **Metadata Population**: Automatic metadata generation
- ✅ **API Calls**: HTTP request handling and error management
- ✅ **CLI Functionality**: Command-line argument parsing and file handling
- ✅ **Configuration**: Token loading and config file management
### Demo Script
Run the demonstration script to see the library in action:
```bash
python test_generate_docs_demo.py
```
This script shows:
- Payload validation examples
- Metadata population demonstration
- API call structure
- Real API testing (if API key is available)
## Usage
### Command Line Options
```bash
adaptsapi [OPTIONS]
```
| Option | Description | Required |
|--------|-------------|----------|
| `--endpoint URL` | Full URL of the API endpoint | Yes (unless set in config.json) |
| `--data JSON` | Inline JSON payload string | Yes (or --payload-file) |
| `--payload-file FILE` | Path to JSON payload file | Yes (or --data) |
| `--timeout SECONDS` | Request timeout in seconds (default: 30) | No |
### Payload Structure
For documentation generation, your payload should follow this structure:
```json
{
"email_address": "user@example.com",
"user_name": "github_username",
"repo_object": {
"repository_name": "my-repo",
"source": "github",
"repository_url": "https://github.com/user/my-repo",
"branch": "main",
"size": "12345",
"language": "python",
"is_private": false,
"git_provider_type": "github",
"refresh_token": "github_token_here"
}
}
```
#### Required Fields
- `email_address`: Valid email address
- `user_name`: Username string
- `repo_object.repository_name`: Repository name
- `repo_object.repository_url`: Full repository URL
- `repo_object.branch`: Branch name
- `repo_object.size`: Repository size as string
- `repo_object.language`: Primary programming language
- `repo_object.source`: Source platform (e.g., "github")
#### Optional Fields
- `repo_object.is_private`: Boolean indicating if repo is private
- `repo_object.git_provider_type`: Git provider type
- `repo_object.installation_id`: Installation ID (for GitHub Apps)
- `repo_object.refresh_token`: Refresh token for authentication
- `repo_object.commit_hash`: Specific commit hash
- `repo_object.commit_message`: Commit message
- `repo_object.commit_author`: Commit author
- `repo_object.directory_name`: Specific directory to process
## GitHub Actions Integration
This package is designed to work seamlessly with GitHub Actions for automated documentation generation. Here's an example workflow:
```yaml
name: Generate Wiki Docs
on:
pull_request:
branches: [ main ]
types: [ closed ]
jobs:
call-adapts-api:
if: github.event.pull_request.merged == true
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Set up Python
uses: actions/setup-python@v5
with:
python-version: "3.11"
- name: Install adaptsapi
run: pip install adaptsapi
- name: Generate documentation
env:
ADAPTS_API_KEY: ${{ secrets.ADAPTS_API_KEY }}
run: |
python -c "
import os
from adaptsapi.generate_docs import post
payload = {
'email_address': '${{ github.actor }}@users.noreply.github.com',
'user_name': '${{ github.actor }}',
'repo_object': {
'repository_name': '${{ github.event.repository.name }}',
'source': 'github',
'repository_url': '${{ github.event.repository.html_url }}',
'branch': 'main',
'size': '0',
'language': 'python',
'is_private': False,
'git_provider_type': 'github',
'refresh_token': '${{ secrets.GITHUB_TOKEN }}'
}
}
resp = post(
'https://your-api-endpoint.com/prod/generate_wiki_docs',
os.environ['ADAPTS_API_KEY'],
payload
)
resp.raise_for_status()
print('✅ Documentation generated successfully')
"
```
### Setting up GitHub Secrets
1. Go to your repository on GitHub
2. Click **Settings** → **Secrets and variables** → **Actions**
3. Click **New repository secret**
4. Add `ADAPTS_API_KEY` with your API token value
## Configuration
### Config File Format
The `config.json` file in your current working directory can contain:
```json
{
"token": "your-api-token-here",
"endpoint": "https://your-default-endpoint.com/prod/generate_wiki_docs"
}
```
### Environment Variables
- `ADAPTS_API_KEY`: Your API authentication token (used by the library)
- `ADAPTS_API_TOKEN`: Alternative token variable (used by CLI)
## Error Handling
The library provides comprehensive error handling:
- **PayloadValidationError**: Raised when payload validation fails
- **ConfigError**: Raised when no token can be found or loaded
- **requests.RequestException**: Raised on network failures
- **JSONDecodeError**: Raised for invalid JSON in config files
### Common Error Scenarios
- **Missing token**: CLI prompts for interactive token input
- **Invalid JSON**: Shows JSON parsing errors
- **API errors**: Displays HTTP status codes and error messages
- **Payload validation**: Shows specific validation failures with field names
## Development
### Prerequisites
- Python 3.10+
- pip
### Setup Development Environment
```bash
git clone https://github.com/adaptsai/adaptsapi.git
cd adaptsapi
python -m venv .venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
pip install -r requirements-dev.txt
pip install -e .
```
### Development Dependencies
Install development dependencies for testing and code quality:
```bash
pip install -r requirements-dev.txt
```
This includes:
- `pytest` - Testing framework
- `pytest-cov` - Coverage reporting
- `pytest-mock` - Mocking utilities
- `flake8` - Code linting
- `mypy` - Type checking
- `black` - Code formatting
- `isort` - Import sorting
### Running Tests
```bash
# Run all tests
python -m pytest
# Run with coverage
python -m pytest --cov=src/adaptsapi --cov-report=html
# Run specific test categories
python -m pytest -m "not integration" # Unit tests only
python -m pytest -m "integration" # Integration tests only
# Run the test runner
python run_tests.py --type all
```
### Code Quality
```bash
# Lint code
flake8 src/adaptsapi tests/
# Type checking
mypy src/adaptsapi/
# Format code
black src/adaptsapi tests/
isort src/adaptsapi tests/
```
## Publishing to PyPI
### Prerequisites
Before publishing to PyPI, ensure you have:
1. **PyPI Account**: Create an account at [pypi.org](https://pypi.org/account/register/)
2. **TestPyPI Account**: Create an account at [test.pypi.org](https://test.pypi.org/account/register/)
3. **API Tokens**: Generate API tokens for both PyPI and TestPyPI
4. **Build Tools**: Install required build tools
```bash
pip install build twine
```
### Build Configuration
The project uses `pyproject.toml` for build configuration. Key settings:
```toml
[project]
name = "adaptsapi"
version = "0.1.4"
description = "CLI to enqueue triggers via internal API Gateway → SNS"
readme = { file = "README.md", content-type = "text/markdown" }
requires-python = ">=3.10"
authors = [
{ name = "VerifyAI Inc.", email = "dev@adapts.ai" }
]
dependencies = [
"requests",
]
```
### Publishing Steps
#### 1. Prepare for Release
```bash
# Clean previous builds
rm -rf build/ dist/ *.egg-info src/*.egg-info
# Update version in pyproject.toml and setup.py
# Edit version numbers in both files
# Run all tests to ensure everything works
python run_tests.py --type all
# Check code quality
flake8 src/adaptsapi tests/
mypy src/adaptsapi/
```
#### 2. Build Distribution Packages
```bash
# Build source distribution and wheel
python -m build
# Verify the built packages
ls -la dist/
# Should show: adaptsapi-0.1.4.tar.gz and adaptsapi-0.1.4-py3-none-any.whl
```
#### 3. Test on TestPyPI (Recommended)
```bash
# Upload to TestPyPI first
python -m twine upload --repository testpypi dist/*
# Test installation from TestPyPI
pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ adaptsapi
# Test the installed package
python -c "from adaptsapi.generate_docs import post; print('✅ Package works!')"
```
#### 4. Publish to PyPI
```bash
# Upload to PyPI
python -m twine upload dist/*
# Verify installation from PyPI
pip install adaptsapi
# Test the installed package
python -c "from adaptsapi.generate_docs import post; print('✅ Package published successfully!')"
```
### Automated Publishing with GitHub Actions
Create `.github/workflows/publish.yml`:
```yaml
name: Publish to PyPI
on:
release:
types: [published]
jobs:
publish:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Set up Python
uses: actions/setup-python@v5
with:
python-version: "3.10"
- name: Install dependencies
run: |
pip install build twine
pip install -r requirements-dev.txt
- name: Run tests
run: |
python run_tests.py --type unit
- name: Build package
run: python -m build
- name: Publish to TestPyPI
env:
TWINE_USERNAME: __token__
TWINE_PASSWORD: ${{ secrets.TEST_PYPI_API_TOKEN }}
run: |
python -m twine upload --repository testpypi dist/*
- name: Publish to PyPI
env:
TWINE_USERNAME: __token__
TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
run: |
python -m twine upload dist/*
```
### Environment Variables for CI/CD
Set these secrets in your GitHub repository:
- `PYPI_API_TOKEN`: Your PyPI API token
- `TEST_PYPI_API_TOKEN`: Your TestPyPI API token
### Version Management
#### Semantic Versioning
Follow [semantic versioning](https://semver.org/):
- **MAJOR.MINOR.PATCH** (e.g., 0.1.4)
- **MAJOR**: Breaking changes
- **MINOR**: New features, backward compatible
- **PATCH**: Bug fixes, backward compatible
#### Update Version Numbers
Update version in these files:
1. **pyproject.toml**:
```toml
[project]
version = "0.1.5" # Update this
```
2. **setup.py**:
```python
setup(
name="adaptsapi",
version="0.1.5", # Update this
# ...
)
```
### Pre-release Checklist
Before publishing, ensure:
- [ ] All tests pass: `python run_tests.py --type all`
- [ ] Code is linted: `flake8 src/adaptsapi tests/`
- [ ] Type checking passes: `mypy src/adaptsapi/`
- [ ] Documentation is updated
- [ ] Version numbers are updated in both `pyproject.toml` and `setup.py`
- [ ] CHANGELOG is updated
- [ ] Package builds successfully: `python -m build`
- [ ] Package installs correctly: `pip install dist/*.whl`
### Troubleshooting
#### Common Issues
1. **"File already exists" error**:
```bash
# Clean previous builds
rm -rf build/ dist/ *.egg-info src/*.egg-info
python -m build
```
2. **Authentication errors**:
```bash
# Check your API token
python -m twine check dist/*
```
3. **Package not found after upload**:
- Wait a few minutes for PyPI to process
- Check the package page: https://pypi.org/project/adaptsapi/
4. **Import errors after installation**:
```bash
# Verify package structure
pip show adaptsapi
python -c "import adaptsapi; print(adaptsapi.__file__)"
```
#### Rollback Strategy
If you need to rollback a release:
1. **Delete the release** (if within 24 hours):
```bash
# Use PyPI web interface to delete the release
# Go to: https://pypi.org/manage/project/adaptsapi/releases/
```
2. **Yank the release** (recommended):
```bash
python -m twine delete --username __token__ --password $PYPI_API_TOKEN adaptsapi 0.1.4
```
3. **Publish a new patch version** with fixes
### Security Best Practices
1. **Use API tokens** instead of username/password
2. **Store tokens securely** in environment variables or secrets
3. **Use TestPyPI** for testing before production
4. **Verify package contents** before uploading
5. **Keep dependencies updated** and secure
### Package Verification
After publishing, verify the package:
```bash
# Install from PyPI
pip install adaptsapi
# Test imports
python -c "
from adaptsapi.generate_docs import post, PayloadValidationError
from adaptsapi.cli import main
from adaptsapi.config import load_token
print('✅ All imports successful!')
"
# Test CLI
adaptsapi --help
# Run tests
python -m pytest tests/test_generate_docs.py -v
```
## API Reference
### Core Functions
#### `post(endpoint, auth_token, payload, timeout=30)`
Make a POST request to the Adapts API with automatic payload validation and metadata population.
**Parameters:**
- `endpoint` (str): The API endpoint URL
- `auth_token` (str): Authentication token
- `payload` (dict): JSON payload to send
- `timeout` (int): Request timeout in seconds (default: 30)
**Returns:**
- `requests.Response`: The HTTP response object
**Raises:**
- `PayloadValidationError`: If payload validation fails
- `requests.RequestException`: If the HTTP request fails
#### `_validate_payload(payload)`
Validate the payload structure and data types.
**Parameters:**
- `payload` (dict): The payload to validate
**Raises:**
- `PayloadValidationError`: If validation fails
#### `_populate_metadata(payload)`
Automatically populate metadata fields in the payload.
**Parameters:**
- `payload` (dict): The payload to populate with metadata
### CLI Functions
#### `main()`
Main CLI entry point that handles argument parsing and API calls.
### Configuration Functions
#### `load_token()`
Load authentication token from environment variables or config file.
**Returns:**
- `str`: The authentication token
**Raises:**
- `ConfigError`: If no token can be found
#### `load_default_endpoint()`
Load default endpoint from config file.
**Returns:**
- `str | None`: The default endpoint URL or None
## Project Structure
```
adaptsapi/
├── src/adaptsapi/
│ ├── __init__.py
│ ├── generate_docs.py # Main API client functionality
│ ├── cli.py # Command-line interface
│ └── config.py # Configuration management
├── tests/
│ ├── conftest.py # Test fixtures and configuration
│ ├── test_generate_docs.py # Tests for generate_docs module
│ ├── test_cli.py # Tests for CLI functionality
│ └── test_config.py # Tests for configuration management
├── run_tests.py # Test runner script
├── test_generate_docs_demo.py # Demonstration script
├── requirements.txt # Runtime dependencies
├── requirements-dev.txt # Development dependencies
├── pytest.ini # Pytest configuration
└── TESTING.md # Detailed testing guide
```
## License
This software is licensed under the Adapts API Use-Only License v1.0. See [LICENSE](LICENSE) for details.
**Key restrictions:**
- ✅ Use the software as-is
- ❌ No modifications allowed
- ❌ No redistribution allowed
- ❌ Commercial use restrictions apply
## Support
- 📧 Email: dev@adapts.ai
- 🐛 Issues: [GitHub Issues](https://github.com/adaptsai/adaptsapi/issues)
- 📖 Documentation: This README and [TESTING.md](TESTING.md)
## Changelog
### v0.1.4 (Latest)
- ✅ Comprehensive test suite with 98% coverage
- ✅ Improved error handling and validation
- ✅ Enhanced CLI functionality
- ✅ Better configuration management
- ✅ Development tools and documentation
### v0.1.3
- Patch updates
### v0.1.2
- Initial stable release
---
© 2025 AdaptsAI All rights reserved.
Raw data
{
"_id": null,
"home_page": "https://github.com/adaptsai/adaptsapi",
"name": "adaptsapi",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "adapts, api, cli, sns",
"author": "adapts",
"author_email": "\"VerifyAI Inc.\" <dev@adapts.ai>",
"download_url": "https://files.pythonhosted.org/packages/6d/ec/76886f2390fce14923aca8dd3497a81b8f2e6b4ee746dfa0d5dff5a7b8d0/adaptsapi-0.1.7.tar.gz",
"platform": null,
"description": "# AdaptsAPI Client\n\nA Python client library and CLI for the Adapts API, designed for triggering documentation generation via API Gateway \u2192 SNS.\n\n[](https://badge.fury.io/py/adaptsapi)\n[](https://www.python.org/downloads/)\n[](LICENSE)\n[](https://github.com/adaptsai/adaptsapi)\n\n## Features\n\n- \ud83d\ude80 **Simple Python Client** for making API calls to Adapts services\n- \ud83d\udd11 **Secure token management** with environment variables or local config\n- \ud83d\udcc4 **Flexible payload support** via JSON files or inline data\n- \ud83d\udd27 **Configurable endpoints** with default endpoint support\n- \u2705 **Built-in payload validation** for documentation generation requests\n- \ud83e\uddea **Comprehensive test suite** with 98% code coverage\n- \ud83e\udd16 **GitHub Actions integration** for automated wiki documentation\n- \ud83d\udce6 **CLI tool** for command-line usage\n\n## Installation\n\n### From PyPI\n\n```bash\npip install adaptsapi\n```\n\n### From Source\n\n```bash\ngit clone https://github.com/adaptsai/adaptsapi.git\ncd adaptsapi\npip install -e .\n```\n\n## Quick Start\n\n### 1. Set up your API token\n\nYou can provide your API token in three ways (in order of precedence):\n\n1. **Environment variable** (recommended for CI/CD):\n ```bash\n export ADAPTS_API_KEY=\"your-api-token-here\"\n ```\n\n2. **Local config file** (`config.json` in current directory):\n ```json\n {\n \"token\": \"your-api-token-here\",\n \"endpoint\": \"https://your-api-endpoint.com/prod/generate_wiki_docs\"\n }\n ```\n\n3. **Interactive prompt** (first-time setup):\n ```bash\n adaptsapi --data '{\"test\": \"payload\"}'\n # CLI will prompt for token and save to config.json\n ```\n\n### 2. Using the Python Client\n\n```python\nfrom adaptsapi.generate_docs import post, PayloadValidationError\n\n# Create your payload\npayload = {\n \"email_address\": \"user@example.com\",\n \"user_name\": \"john_doe\",\n \"repo_object\": {\n \"repository_name\": \"my-repo\",\n \"source\": \"github\",\n \"repository_url\": \"https://github.com/user/my-repo\",\n \"branch\": \"main\",\n \"size\": \"12345\",\n \"language\": \"python\",\n \"is_private\": False,\n \"git_provider_type\": \"github\",\n \"refresh_token\": \"github_token_here\"\n }\n}\n\n# Make the API call\ntry:\n response = post(\n \"https://api.adapts.ai/prod/generate_wiki_docs\",\n \"your-api-token\",\n payload\n )\n response.raise_for_status()\n result = response.json()\n print(\"\u2705 Success:\", result)\nexcept PayloadValidationError as e:\n print(f\"\u274c Validation error: {e}\")\nexcept Exception as e:\n print(f\"\u274c API error: {e}\")\n```\n\n### 3. Using the CLI\n\n**Using inline JSON data:**\n```bash\nadaptsapi \\\n --endpoint \"https://api.adapts.ai/prod/generate_wiki_docs\" \\\n --data '{\"email_address\": \"user@example.com\", \"user_name\": \"john_doe\", \"repo_object\": {...}}'\n```\n\n**Using a JSON payload file:**\n```bash\nadaptsapi \\\n --endpoint \"https://api.adapts.ai/prod/generate_wiki_docs\" \\\n --payload-file payload.json\n```\n\n## Testing\n\nThe library includes a comprehensive test suite with 98% code coverage.\n\n### Running Tests\n\n#### Quick Test Run\n```bash\n# Run all tests\npython -m pytest\n\n# Run with verbose output\npython -m pytest -v\n\n# Run specific test file\npython -m pytest tests/test_generate_docs.py\n\n# Run with coverage report\npython -m pytest --cov=src/adaptsapi --cov-report=html\n```\n\n#### Using the Test Runner\n```bash\n# Run unit tests only (fast, no external dependencies)\npython run_tests.py --type unit\n\n# Run integration tests (requires API key)\npython run_tests.py --type integration\n\n# Run all tests with coverage\npython run_tests.py --type coverage\n\n# Run with custom API key\npython run_tests.py --type integration --api-key \"your-api-key\"\n```\n\n#### Test Categories\n\n- **Unit Tests**: Fast tests that mock external dependencies\n- **Integration Tests**: Tests that make real API calls (marked with `@pytest.mark.integration`)\n- **CLI Tests**: Tests for command-line interface functionality\n- **Config Tests**: Tests for configuration management\n\n### Test Coverage\n\nThe test suite covers:\n\n- \u2705 **Payload Validation**: All validation logic and error cases\n- \u2705 **Metadata Population**: Automatic metadata generation\n- \u2705 **API Calls**: HTTP request handling and error management\n- \u2705 **CLI Functionality**: Command-line argument parsing and file handling\n- \u2705 **Configuration**: Token loading and config file management\n\n### Demo Script\n\nRun the demonstration script to see the library in action:\n\n```bash\npython test_generate_docs_demo.py\n```\n\nThis script shows:\n- Payload validation examples\n- Metadata population demonstration\n- API call structure\n- Real API testing (if API key is available)\n\n## Usage\n\n### Command Line Options\n\n```bash\nadaptsapi [OPTIONS]\n```\n\n| Option | Description | Required |\n|--------|-------------|----------|\n| `--endpoint URL` | Full URL of the API endpoint | Yes (unless set in config.json) |\n| `--data JSON` | Inline JSON payload string | Yes (or --payload-file) |\n| `--payload-file FILE` | Path to JSON payload file | Yes (or --data) |\n| `--timeout SECONDS` | Request timeout in seconds (default: 30) | No |\n\n### Payload Structure\n\nFor documentation generation, your payload should follow this structure:\n\n```json\n{\n \"email_address\": \"user@example.com\",\n \"user_name\": \"github_username\",\n \"repo_object\": {\n \"repository_name\": \"my-repo\",\n \"source\": \"github\",\n \"repository_url\": \"https://github.com/user/my-repo\",\n \"branch\": \"main\",\n \"size\": \"12345\",\n \"language\": \"python\",\n \"is_private\": false,\n \"git_provider_type\": \"github\",\n \"refresh_token\": \"github_token_here\"\n }\n}\n```\n\n#### Required Fields\n\n- `email_address`: Valid email address\n- `user_name`: Username string\n- `repo_object.repository_name`: Repository name\n- `repo_object.repository_url`: Full repository URL\n- `repo_object.branch`: Branch name\n- `repo_object.size`: Repository size as string\n- `repo_object.language`: Primary programming language\n- `repo_object.source`: Source platform (e.g., \"github\")\n\n#### Optional Fields\n\n- `repo_object.is_private`: Boolean indicating if repo is private\n- `repo_object.git_provider_type`: Git provider type\n- `repo_object.installation_id`: Installation ID (for GitHub Apps)\n- `repo_object.refresh_token`: Refresh token for authentication\n- `repo_object.commit_hash`: Specific commit hash\n- `repo_object.commit_message`: Commit message\n- `repo_object.commit_author`: Commit author\n- `repo_object.directory_name`: Specific directory to process\n\n## GitHub Actions Integration\n\nThis package is designed to work seamlessly with GitHub Actions for automated documentation generation. Here's an example workflow:\n\n```yaml\nname: Generate Wiki Docs\n\non:\n pull_request:\n branches: [ main ]\n types: [ closed ]\n\njobs:\n call-adapts-api:\n if: github.event.pull_request.merged == true\n runs-on: ubuntu-latest\n \n steps:\n - uses: actions/checkout@v4\n \n - name: Set up Python\n uses: actions/setup-python@v5\n with:\n python-version: \"3.11\"\n \n - name: Install adaptsapi\n run: pip install adaptsapi\n \n - name: Generate documentation\n env:\n ADAPTS_API_KEY: ${{ secrets.ADAPTS_API_KEY }}\n run: |\n python -c \"\n import os\n from adaptsapi.generate_docs import post\n \n payload = {\n 'email_address': '${{ github.actor }}@users.noreply.github.com',\n 'user_name': '${{ github.actor }}',\n 'repo_object': {\n 'repository_name': '${{ github.event.repository.name }}',\n 'source': 'github',\n 'repository_url': '${{ github.event.repository.html_url }}',\n 'branch': 'main',\n 'size': '0',\n 'language': 'python',\n 'is_private': False,\n 'git_provider_type': 'github',\n 'refresh_token': '${{ secrets.GITHUB_TOKEN }}'\n }\n }\n \n resp = post(\n 'https://your-api-endpoint.com/prod/generate_wiki_docs',\n os.environ['ADAPTS_API_KEY'],\n payload\n )\n resp.raise_for_status()\n print('\u2705 Documentation generated successfully')\n \"\n```\n\n### Setting up GitHub Secrets\n\n1. Go to your repository on GitHub\n2. Click **Settings** \u2192 **Secrets and variables** \u2192 **Actions**\n3. Click **New repository secret**\n4. Add `ADAPTS_API_KEY` with your API token value\n\n## Configuration\n\n### Config File Format\n\nThe `config.json` file in your current working directory can contain:\n\n```json\n{\n \"token\": \"your-api-token-here\",\n \"endpoint\": \"https://your-default-endpoint.com/prod/generate_wiki_docs\"\n}\n```\n\n### Environment Variables\n\n- `ADAPTS_API_KEY`: Your API authentication token (used by the library)\n- `ADAPTS_API_TOKEN`: Alternative token variable (used by CLI)\n\n## Error Handling\n\nThe library provides comprehensive error handling:\n\n- **PayloadValidationError**: Raised when payload validation fails\n- **ConfigError**: Raised when no token can be found or loaded\n- **requests.RequestException**: Raised on network failures\n- **JSONDecodeError**: Raised for invalid JSON in config files\n\n### Common Error Scenarios\n\n- **Missing token**: CLI prompts for interactive token input\n- **Invalid JSON**: Shows JSON parsing errors\n- **API errors**: Displays HTTP status codes and error messages\n- **Payload validation**: Shows specific validation failures with field names\n\n## Development\n\n### Prerequisites\n\n- Python 3.10+\n- pip\n\n### Setup Development Environment\n\n```bash\ngit clone https://github.com/adaptsai/adaptsapi.git\ncd adaptsapi\npython -m venv .venv\nsource .venv/bin/activate # On Windows: .venv\\Scripts\\activate\npip install -r requirements-dev.txt\npip install -e .\n```\n\n### Development Dependencies\n\nInstall development dependencies for testing and code quality:\n\n```bash\npip install -r requirements-dev.txt\n```\n\nThis includes:\n- `pytest` - Testing framework\n- `pytest-cov` - Coverage reporting\n- `pytest-mock` - Mocking utilities\n- `flake8` - Code linting\n- `mypy` - Type checking\n- `black` - Code formatting\n- `isort` - Import sorting\n\n### Running Tests\n\n```bash\n# Run all tests\npython -m pytest\n\n# Run with coverage\npython -m pytest --cov=src/adaptsapi --cov-report=html\n\n# Run specific test categories\npython -m pytest -m \"not integration\" # Unit tests only\npython -m pytest -m \"integration\" # Integration tests only\n\n# Run the test runner\npython run_tests.py --type all\n```\n\n### Code Quality\n\n```bash\n# Lint code\nflake8 src/adaptsapi tests/\n\n# Type checking\nmypy src/adaptsapi/\n\n# Format code\nblack src/adaptsapi tests/\nisort src/adaptsapi tests/\n```\n\n## Publishing to PyPI\n\n### Prerequisites\n\nBefore publishing to PyPI, ensure you have:\n\n1. **PyPI Account**: Create an account at [pypi.org](https://pypi.org/account/register/)\n2. **TestPyPI Account**: Create an account at [test.pypi.org](https://test.pypi.org/account/register/)\n3. **API Tokens**: Generate API tokens for both PyPI and TestPyPI\n4. **Build Tools**: Install required build tools\n\n```bash\npip install build twine\n```\n\n### Build Configuration\n\nThe project uses `pyproject.toml` for build configuration. Key settings:\n\n```toml\n[project]\nname = \"adaptsapi\"\nversion = \"0.1.4\"\ndescription = \"CLI to enqueue triggers via internal API Gateway \u2192 SNS\"\nreadme = { file = \"README.md\", content-type = \"text/markdown\" }\nrequires-python = \">=3.10\"\nauthors = [\n { name = \"VerifyAI Inc.\", email = \"dev@adapts.ai\" }\n]\ndependencies = [\n \"requests\",\n]\n```\n\n### Publishing Steps\n\n#### 1. Prepare for Release\n\n```bash\n# Clean previous builds\nrm -rf build/ dist/ *.egg-info src/*.egg-info\n\n# Update version in pyproject.toml and setup.py\n# Edit version numbers in both files\n\n# Run all tests to ensure everything works\npython run_tests.py --type all\n\n# Check code quality\nflake8 src/adaptsapi tests/\nmypy src/adaptsapi/\n```\n\n#### 2. Build Distribution Packages\n\n```bash\n# Build source distribution and wheel\npython -m build\n\n# Verify the built packages\nls -la dist/\n# Should show: adaptsapi-0.1.4.tar.gz and adaptsapi-0.1.4-py3-none-any.whl\n```\n\n#### 3. Test on TestPyPI (Recommended)\n\n```bash\n# Upload to TestPyPI first\npython -m twine upload --repository testpypi dist/*\n\n# Test installation from TestPyPI\npip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ adaptsapi\n\n# Test the installed package\npython -c \"from adaptsapi.generate_docs import post; print('\u2705 Package works!')\"\n```\n\n#### 4. Publish to PyPI\n\n```bash\n# Upload to PyPI\npython -m twine upload dist/*\n\n# Verify installation from PyPI\npip install adaptsapi\n\n# Test the installed package\npython -c \"from adaptsapi.generate_docs import post; print('\u2705 Package published successfully!')\"\n```\n\n### Automated Publishing with GitHub Actions\n\nCreate `.github/workflows/publish.yml`:\n\n```yaml\nname: Publish to PyPI\n\non:\n release:\n types: [published]\n\njobs:\n publish:\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v4\n \n - name: Set up Python\n uses: actions/setup-python@v5\n with:\n python-version: \"3.10\"\n \n - name: Install dependencies\n run: |\n pip install build twine\n pip install -r requirements-dev.txt\n \n - name: Run tests\n run: |\n python run_tests.py --type unit\n \n - name: Build package\n run: python -m build\n \n - name: Publish to TestPyPI\n env:\n TWINE_USERNAME: __token__\n TWINE_PASSWORD: ${{ secrets.TEST_PYPI_API_TOKEN }}\n run: |\n python -m twine upload --repository testpypi dist/*\n \n - name: Publish to PyPI\n env:\n TWINE_USERNAME: __token__\n TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}\n run: |\n python -m twine upload dist/*\n```\n\n### Environment Variables for CI/CD\n\nSet these secrets in your GitHub repository:\n\n- `PYPI_API_TOKEN`: Your PyPI API token\n- `TEST_PYPI_API_TOKEN`: Your TestPyPI API token\n\n### Version Management\n\n#### Semantic Versioning\n\nFollow [semantic versioning](https://semver.org/):\n\n- **MAJOR.MINOR.PATCH** (e.g., 0.1.4)\n- **MAJOR**: Breaking changes\n- **MINOR**: New features, backward compatible\n- **PATCH**: Bug fixes, backward compatible\n\n#### Update Version Numbers\n\nUpdate version in these files:\n\n1. **pyproject.toml**:\n ```toml\n [project]\n version = \"0.1.5\" # Update this\n ```\n\n2. **setup.py**:\n ```python\n setup(\n name=\"adaptsapi\",\n version=\"0.1.5\", # Update this\n # ...\n )\n ```\n\n### Pre-release Checklist\n\nBefore publishing, ensure:\n\n- [ ] All tests pass: `python run_tests.py --type all`\n- [ ] Code is linted: `flake8 src/adaptsapi tests/`\n- [ ] Type checking passes: `mypy src/adaptsapi/`\n- [ ] Documentation is updated\n- [ ] Version numbers are updated in both `pyproject.toml` and `setup.py`\n- [ ] CHANGELOG is updated\n- [ ] Package builds successfully: `python -m build`\n- [ ] Package installs correctly: `pip install dist/*.whl`\n\n### Troubleshooting\n\n#### Common Issues\n\n1. **\"File already exists\" error**:\n ```bash\n # Clean previous builds\n rm -rf build/ dist/ *.egg-info src/*.egg-info\n python -m build\n ```\n\n2. **Authentication errors**:\n ```bash\n # Check your API token\n python -m twine check dist/*\n ```\n\n3. **Package not found after upload**:\n - Wait a few minutes for PyPI to process\n - Check the package page: https://pypi.org/project/adaptsapi/\n\n4. **Import errors after installation**:\n ```bash\n # Verify package structure\n pip show adaptsapi\n python -c \"import adaptsapi; print(adaptsapi.__file__)\"\n ```\n\n#### Rollback Strategy\n\nIf you need to rollback a release:\n\n1. **Delete the release** (if within 24 hours):\n ```bash\n # Use PyPI web interface to delete the release\n # Go to: https://pypi.org/manage/project/adaptsapi/releases/\n ```\n\n2. **Yank the release** (recommended):\n ```bash\n python -m twine delete --username __token__ --password $PYPI_API_TOKEN adaptsapi 0.1.4\n ```\n\n3. **Publish a new patch version** with fixes\n\n### Security Best Practices\n\n1. **Use API tokens** instead of username/password\n2. **Store tokens securely** in environment variables or secrets\n3. **Use TestPyPI** for testing before production\n4. **Verify package contents** before uploading\n5. **Keep dependencies updated** and secure\n\n### Package Verification\n\nAfter publishing, verify the package:\n\n```bash\n# Install from PyPI\npip install adaptsapi\n\n# Test imports\npython -c \"\nfrom adaptsapi.generate_docs import post, PayloadValidationError\nfrom adaptsapi.cli import main\nfrom adaptsapi.config import load_token\nprint('\u2705 All imports successful!')\n\"\n\n# Test CLI\nadaptsapi --help\n\n# Run tests\npython -m pytest tests/test_generate_docs.py -v\n```\n\n## API Reference\n\n### Core Functions\n\n#### `post(endpoint, auth_token, payload, timeout=30)`\n\nMake a POST request to the Adapts API with automatic payload validation and metadata population.\n\n**Parameters:**\n- `endpoint` (str): The API endpoint URL\n- `auth_token` (str): Authentication token\n- `payload` (dict): JSON payload to send\n- `timeout` (int): Request timeout in seconds (default: 30)\n\n**Returns:**\n- `requests.Response`: The HTTP response object\n\n**Raises:**\n- `PayloadValidationError`: If payload validation fails\n- `requests.RequestException`: If the HTTP request fails\n\n#### `_validate_payload(payload)`\n\nValidate the payload structure and data types.\n\n**Parameters:**\n- `payload` (dict): The payload to validate\n\n**Raises:**\n- `PayloadValidationError`: If validation fails\n\n#### `_populate_metadata(payload)`\n\nAutomatically populate metadata fields in the payload.\n\n**Parameters:**\n- `payload` (dict): The payload to populate with metadata\n\n### CLI Functions\n\n#### `main()`\n\nMain CLI entry point that handles argument parsing and API calls.\n\n### Configuration Functions\n\n#### `load_token()`\n\nLoad authentication token from environment variables or config file.\n\n**Returns:**\n- `str`: The authentication token\n\n**Raises:**\n- `ConfigError`: If no token can be found\n\n#### `load_default_endpoint()`\n\nLoad default endpoint from config file.\n\n**Returns:**\n- `str | None`: The default endpoint URL or None\n\n## Project Structure\n\n```\nadaptsapi/\n\u251c\u2500\u2500 src/adaptsapi/\n\u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u251c\u2500\u2500 generate_docs.py # Main API client functionality\n\u2502 \u251c\u2500\u2500 cli.py # Command-line interface\n\u2502 \u2514\u2500\u2500 config.py # Configuration management\n\u251c\u2500\u2500 tests/\n\u2502 \u251c\u2500\u2500 conftest.py # Test fixtures and configuration\n\u2502 \u251c\u2500\u2500 test_generate_docs.py # Tests for generate_docs module\n\u2502 \u251c\u2500\u2500 test_cli.py # Tests for CLI functionality\n\u2502 \u2514\u2500\u2500 test_config.py # Tests for configuration management\n\u251c\u2500\u2500 run_tests.py # Test runner script\n\u251c\u2500\u2500 test_generate_docs_demo.py # Demonstration script\n\u251c\u2500\u2500 requirements.txt # Runtime dependencies\n\u251c\u2500\u2500 requirements-dev.txt # Development dependencies\n\u251c\u2500\u2500 pytest.ini # Pytest configuration\n\u2514\u2500\u2500 TESTING.md # Detailed testing guide\n```\n\n## License\n\nThis software is licensed under the Adapts API Use-Only License v1.0. See [LICENSE](LICENSE) for details.\n\n**Key restrictions:**\n- \u2705 Use the software as-is\n- \u274c No modifications allowed\n- \u274c No redistribution allowed\n- \u274c Commercial use restrictions apply\n\n## Support\n\n- \ud83d\udce7 Email: dev@adapts.ai\n- \ud83d\udc1b Issues: [GitHub Issues](https://github.com/adaptsai/adaptsapi/issues)\n- \ud83d\udcd6 Documentation: This README and [TESTING.md](TESTING.md)\n\n## Changelog\n\n### v0.1.4 (Latest)\n- \u2705 Comprehensive test suite with 98% coverage\n- \u2705 Improved error handling and validation\n- \u2705 Enhanced CLI functionality\n- \u2705 Better configuration management\n- \u2705 Development tools and documentation\n\n### v0.1.3\n- Patch updates\n\n### v0.1.2\n- Initial stable release\n\n---\n\n\u00a9 2025 AdaptsAI All rights reserved.\n",
"bugtrack_url": null,
"license": null,
"summary": "CLI to enqueue triggers via internal API Gateway \u2192 SNS",
"version": "0.1.7",
"project_urls": {
"Homepage": "https://github.com/adaptsai/adaptsapi",
"Source": "https://github.com/adaptsai/adaptsapi"
},
"split_keywords": [
"adapts",
" api",
" cli",
" sns"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "8258b8c3c1419197b9fd89e83276a5a53602b8bbc622f40602a9456e7271fe71",
"md5": "0c7510da49091217a33db5a71677c7dc",
"sha256": "255f01042c11130df362ed193b355cb381ed918da1dccf12f829f886b71c1b16"
},
"downloads": -1,
"filename": "adaptsapi-0.1.7-py3-none-any.whl",
"has_sig": false,
"md5_digest": "0c7510da49091217a33db5a71677c7dc",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 12176,
"upload_time": "2025-07-21T10:23:03",
"upload_time_iso_8601": "2025-07-21T10:23:03.421730Z",
"url": "https://files.pythonhosted.org/packages/82/58/b8c3c1419197b9fd89e83276a5a53602b8bbc622f40602a9456e7271fe71/adaptsapi-0.1.7-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "6dec76886f2390fce14923aca8dd3497a81b8f2e6b4ee746dfa0d5dff5a7b8d0",
"md5": "ff87df3138b37ec26553f36c4e92a92b",
"sha256": "de6b3d946a2863bccb5e67af54cf7e020d3f71bb22f3b32b25728000e002b22f"
},
"downloads": -1,
"filename": "adaptsapi-0.1.7.tar.gz",
"has_sig": false,
"md5_digest": "ff87df3138b37ec26553f36c4e92a92b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 22873,
"upload_time": "2025-07-21T10:23:05",
"upload_time_iso_8601": "2025-07-21T10:23:05.899741Z",
"url": "https://files.pythonhosted.org/packages/6d/ec/76886f2390fce14923aca8dd3497a81b8f2e6b4ee746dfa0d5dff5a7b8d0/adaptsapi-0.1.7.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-21 10:23:05",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "adaptsai",
"github_project": "adaptsapi",
"github_not_found": true,
"lcname": "adaptsapi"
}
JSON
