| Name | ukcompanies JSON |
| Version |
0.6.1
JSON |
| download |
| home_page | None |
| Summary | A Python SDK for accessing UK Companies House API |
| upload_time | 2025-08-15 15:20:17 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.10 |
| license | MIT |
| keywords |
api
business
companies
data
house
sdk
uk
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# UK Companies SDK
A modern Python SDK for accessing the UK Companies House API.
## Features
- **Async-first**: Built with modern async/await patterns for optimal performance
- **Type-safe**: Full type hints and Pydantic models for data validation
- **Developer-friendly**: Intuitive API with comprehensive documentation
- **Lightweight**: Minimal dependencies, fast installation
- **Well-tested**: Extensive test coverage with unit and integration tests
- **Automatic Retry**: Smart retry logic with exponential backoff for rate-limited requests
- **Rate Limit Aware**: Intelligent handling of API rate limits with configurable retry strategies
- **Production Ready**: Published on PyPI, thoroughly tested with live API
## Installation
```bash
# Install from PyPI
pip install ukcompanies
# Or with uv
uv add ukcompanies
```
## Quick Start
```python
import asyncio
from ukcompanies import AsyncClient
async def main():
# Initialize the client with your API key
async with AsyncClient(api_key="your-api-key") as client:
# Search for companies
results = await client.search_companies("OpenAI")
for company in results.items:
print(f"{company.title} - {company.company_number}")
# Get detailed company information
company = await client.profile("12345678")
print(f"Company: {company.company_name}")
print(f"Status: {company.company_status}")
asyncio.run(main())
```
## Configuration
### API Key
You'll need an API key from Companies House. Get one by:
1. Registering at [Companies House Developer Hub](https://developer.company-information.service.gov.uk/)
2. Creating an application
3. Getting your API key
### Environment Variables
Create a `.env` file in your project root:
```bash
COMPANIES_HOUSE_API_KEY=your-api-key-here
```
## Advanced Configuration
### Retry Settings
The SDK automatically handles rate limits with intelligent retry logic. You can customize retry behavior:
```python
from ukcompanies import AsyncClient
# Custom retry configuration
async with AsyncClient(
api_key="your-api-key",
auto_retry=True, # Enable automatic retry (default: True)
max_retries=5, # Maximum retry attempts (default: 3)
backoff="exponential", # Backoff strategy: "exponential" or "fixed" (default: "exponential")
base_delay=1.0, # Base delay in seconds (default: 1.0)
max_delay=60.0, # Maximum delay between retries (default: 60.0)
jitter_range=1.0, # Random jitter range (default: 1.0)
on_retry=my_callback # Optional callback for retry events
) as client:
# Use client here
pass
# Custom retry callback
async def my_retry_callback(attempt, delay, response):
print(f"Retry attempt {attempt} after {delay}s delay")
async with AsyncClient(
api_key="your-api-key",
on_retry=my_retry_callback
) as client:
# Use client here
pass
```
The SDK respects `X-Ratelimit-Reset` headers from the API for intelligent wait times and uses exponential backoff with jitter to prevent thundering herd problems.
## Development
### Setup
This project uses `uv` for dependency management:
```bash
# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh
# Install dependencies
uv pip install -e ".[dev]"
```
### Testing
```bash
# Run tests
pytest
# Run tests with coverage
pytest --cov=ukcompanies
# Run type checking
mypy src/ukcompanies
# Run linting
ruff check src/ tests/
# Format code
ruff format src/ tests/
```
### Documentation
Documentation is built with MkDocs:
```bash
# Install documentation dependencies
uv pip install -e ".[docs]"
# Serve documentation locally
mkdocs serve
# Build documentation
mkdocs build
```
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Links
- [Documentation](https://github.com/yourusername/ukcompanies)
- [PyPI Package](https://pypi.org/project/ukcompanies/)
- [Companies House API Documentation](https://developer.company-information.service.gov.uk/api/docs/)
Raw data
{
"_id": null,
"home_page": null,
"name": "ukcompanies",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "api, business, companies, data, house, sdk, uk",
"author": null,
"author_email": "Development Team <dev@example.com>",
"download_url": "https://files.pythonhosted.org/packages/fe/80/9a733e856aeec0dac1a163cdd0db3bea85db362c58552ad0563bf1c0b129/ukcompanies-0.6.1.tar.gz",
"platform": null,
"description": "# UK Companies SDK\n\nA modern Python SDK for accessing the UK Companies House API.\n\n## Features\n\n- **Async-first**: Built with modern async/await patterns for optimal performance\n- **Type-safe**: Full type hints and Pydantic models for data validation \n- **Developer-friendly**: Intuitive API with comprehensive documentation\n- **Lightweight**: Minimal dependencies, fast installation\n- **Well-tested**: Extensive test coverage with unit and integration tests\n- **Automatic Retry**: Smart retry logic with exponential backoff for rate-limited requests\n- **Rate Limit Aware**: Intelligent handling of API rate limits with configurable retry strategies\n- **Production Ready**: Published on PyPI, thoroughly tested with live API\n\n## Installation\n\n```bash\n# Install from PyPI\npip install ukcompanies\n\n# Or with uv\nuv add ukcompanies\n```\n\n## Quick Start\n\n```python\nimport asyncio\nfrom ukcompanies import AsyncClient\n\nasync def main():\n # Initialize the client with your API key\n async with AsyncClient(api_key=\"your-api-key\") as client:\n # Search for companies\n results = await client.search_companies(\"OpenAI\")\n \n for company in results.items:\n print(f\"{company.title} - {company.company_number}\")\n \n # Get detailed company information\n company = await client.profile(\"12345678\")\n print(f\"Company: {company.company_name}\")\n print(f\"Status: {company.company_status}\")\n\nasyncio.run(main())\n```\n\n## Configuration\n\n### API Key\n\nYou'll need an API key from Companies House. Get one by:\n\n1. Registering at [Companies House Developer Hub](https://developer.company-information.service.gov.uk/)\n2. Creating an application\n3. Getting your API key\n\n### Environment Variables\n\nCreate a `.env` file in your project root:\n\n```bash\nCOMPANIES_HOUSE_API_KEY=your-api-key-here\n```\n\n## Advanced Configuration\n\n### Retry Settings\n\nThe SDK automatically handles rate limits with intelligent retry logic. You can customize retry behavior:\n\n```python\nfrom ukcompanies import AsyncClient\n\n# Custom retry configuration\nasync with AsyncClient(\n api_key=\"your-api-key\",\n auto_retry=True, # Enable automatic retry (default: True)\n max_retries=5, # Maximum retry attempts (default: 3)\n backoff=\"exponential\", # Backoff strategy: \"exponential\" or \"fixed\" (default: \"exponential\")\n base_delay=1.0, # Base delay in seconds (default: 1.0)\n max_delay=60.0, # Maximum delay between retries (default: 60.0)\n jitter_range=1.0, # Random jitter range (default: 1.0)\n on_retry=my_callback # Optional callback for retry events\n) as client:\n # Use client here\n pass\n\n# Custom retry callback\nasync def my_retry_callback(attempt, delay, response):\n print(f\"Retry attempt {attempt} after {delay}s delay\")\n\nasync with AsyncClient(\n api_key=\"your-api-key\",\n on_retry=my_retry_callback\n) as client:\n # Use client here\n pass\n```\n\nThe SDK respects `X-Ratelimit-Reset` headers from the API for intelligent wait times and uses exponential backoff with jitter to prevent thundering herd problems.\n\n## Development\n\n### Setup\n\nThis project uses `uv` for dependency management:\n\n```bash\n# Install uv\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n\n# Install dependencies\nuv pip install -e \".[dev]\"\n```\n\n### Testing\n\n```bash\n# Run tests\npytest\n\n# Run tests with coverage\npytest --cov=ukcompanies\n\n# Run type checking\nmypy src/ukcompanies\n\n# Run linting\nruff check src/ tests/\n\n# Format code\nruff format src/ tests/\n```\n\n### Documentation\n\nDocumentation is built with MkDocs:\n\n```bash\n# Install documentation dependencies\nuv pip install -e \".[docs]\"\n\n# Serve documentation locally\nmkdocs serve\n\n# Build documentation\nmkdocs build\n```\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Links\n\n- [Documentation](https://github.com/yourusername/ukcompanies)\n- [PyPI Package](https://pypi.org/project/ukcompanies/)\n- [Companies House API Documentation](https://developer.company-information.service.gov.uk/api/docs/)",
"bugtrack_url": null,
"license": "MIT",
"summary": "A Python SDK for accessing UK Companies House API",
"version": "0.6.1",
"project_urls": {
"documentation": "https://github.com/dkellett/ukcompanies/tree/main/docs",
"homepage": "https://github.com/dkellett/ukcompanies",
"repository": "https://github.com/dkellett/ukcompanies"
},
"split_keywords": [
"api",
" business",
" companies",
" data",
" house",
" sdk",
" uk"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "3e102fa7fe6b3455783f6369ec0ceab5d186d058c19dfa511b06a5e41507f344",
"md5": "4d4d2086283cdedbcb33f8455c4d6b89",
"sha256": "d337070fa7e19da0c44cba5ab2de2738c89af75d6038b77a089803f6ce3cfe25"
},
"downloads": -1,
"filename": "ukcompanies-0.6.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "4d4d2086283cdedbcb33f8455c4d6b89",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 34693,
"upload_time": "2025-08-15T15:20:15",
"upload_time_iso_8601": "2025-08-15T15:20:15.591655Z",
"url": "https://files.pythonhosted.org/packages/3e/10/2fa7fe6b3455783f6369ec0ceab5d186d058c19dfa511b06a5e41507f344/ukcompanies-0.6.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "fe809a733e856aeec0dac1a163cdd0db3bea85db362c58552ad0563bf1c0b129",
"md5": "56bb9b9438eb068ae61833c45e069fc0",
"sha256": "fc9e2509a27ed3eac16c09c1ef07f87cc0eeea375076d89e07c6821a62ae4726"
},
"downloads": -1,
"filename": "ukcompanies-0.6.1.tar.gz",
"has_sig": false,
"md5_digest": "56bb9b9438eb068ae61833c45e069fc0",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 1428240,
"upload_time": "2025-08-15T15:20:17",
"upload_time_iso_8601": "2025-08-15T15:20:17.460151Z",
"url": "https://files.pythonhosted.org/packages/fe/80/9a733e856aeec0dac1a163cdd0db3bea85db362c58552ad0563bf1c0b129/ukcompanies-0.6.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-15 15:20:17",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "dkellett",
"github_project": "ukcompanies",
"github_not_found": true,
"lcname": "ukcompanies"
}
