Metadata-Version: 2.4
Name: devpost-api
Version: 1.0.1
Summary: Unofficial Devpost API client with resilient scraping, typed models, and CLI tooling.
Project-URL: Homepage, https://github.com/ch1kim0n1/devpost-api
Project-URL: Repository, https://github.com/ch1kim0n1/devpost-api
Project-URL: Issues, https://github.com/ch1kim0n1/devpost-api/issues
Author: Vladislav Kondratyev
License: MIT
License-File: LICENSE
Keywords: api,devpost,github,hackathon,scraping
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
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
Classifier: Typing :: Typed
Requires-Python: >=3.9
Provides-Extra: dev
Requires-Dist: build>=1.2.2; extra == 'dev'
Requires-Dist: coverage[toml]>=7.6.0; extra == 'dev'
Requires-Dist: mypy>=1.14.0; extra == 'dev'
Requires-Dist: ruff>=0.9.0; extra == 'dev'
Requires-Dist: twine>=6.1.0; extra == 'dev'
Description-Content-Type: text/markdown

# devpost-api

Unofficial Devpost API and scraping client for hackathon scouting workflows.

[![CI](https://github.com/ch1kim0n1/devpost-api/actions/workflows/ci.yml/badge.svg)](https://github.com/ch1kim0n1/devpost-api/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/devpost-api.svg)](https://pypi.org/project/devpost-api/)
[![Python](https://img.shields.io/pypi/pyversions/devpost-api.svg)](https://pypi.org/project/devpost-api/)
[![License](https://img.shields.io/pypi/l/devpost-api.svg)](LICENSE)

## Why use this package

- No runtime dependencies (stdlib only)
- Typed models and predictable public API
- Built-in retries, exponential backoff, and rate-limit handling
- Optional request throttling, cache, and parallel fetch
- CLI designed for scripts (`json`, `jsonl`, `csv`, `table`)

## Naming and install model

- Install package: `pip install devpost-api`
- Python import path: `import devpost_api`
- CLI command: `devpost-api`

## Install

```bash
pip install devpost-api
```

From source:

```bash
pip install -e ".[dev]"
```

## Quickstart (Python)

```python
from devpost_api import DevpostClient, RetryConfig

client = DevpostClient(
    retry_config=RetryConfig(max_attempts=4, backoff_factor=0.5),
    max_workers=8,
    min_request_interval=0.05,
    cache_ttl=30.0,
)

for project in client.iter_software(query="ai", max_pages=2):
    print(project.name)

batch = client.collect_projects(
    [
        "https://devpost.com/software/api",
        "https://devpost.com/software/does-not-exist",
    ],
    include_github=True,
)
print(len(batch.projects), len(batch.failures))
```

## Quickstart (CLI)

```bash
# JSON (default)
devpost-api software --query ai --page 1

# CSV for shell pipelines
devpost-api --format csv --fields name,url software --query ai --page 1

# Batch project fetch from a file (one URL/slug per line)
devpost-api --format jsonl project --input-file projects.txt --with-github --best-effort

# Batch GitHub enrichment from stdin
printf "openai/openai-python\npsf/requests\n" | devpost-api github --stdin --best-effort --format table
```

If `devpost-api` is not on your `PATH`, use `python -m devpost_api.cli ...`.

## Public API

- `DevpostClient.list_software(page=1, query=None)`
- `DevpostClient.list_users(page=1)`
- `DevpostClient.list_hackathons(page=1, status=None)`
- `DevpostClient.iter_software(query=None, start_page=1, max_pages=None)`
- `DevpostClient.iter_users(start_page=1, max_pages=None)`
- `DevpostClient.iter_hackathons(status=None, start_page=1, max_pages=None)`
- `DevpostClient.get_project(slug_or_url, include_github=False, raise_on_error=True)`
- `DevpostClient.get_projects(slugs_or_urls, include_github=False, raise_on_error=True)`
- `DevpostClient.collect_projects(slugs_or_urls, include_github=False)`
- `DevpostClient.get_github_repo(url_or_owner_repo)`
- `DevpostClient.get_github_repos(urls_or_owner_repo, raise_on_error=True)`
- `DevpostClient.list_hackathon_project_urls(hackathon_slug_or_url, pages=1)`
- `DevpostClient.scout_hackathon_projects(hackathon_slug_or_url, pages=1, include_github=False, raise_on_error=True)`
- `DevpostClient.clear_cache()`

## Reliability knobs

- `--retries`, `--backoff`, `--max-backoff`, `--jitter`
- `--workers` for parallel bulk operations
- `--min-interval` for global request spacing
- `--cache-ttl` for in-memory GET cache
- `--best-effort` for batch item error tolerance

## Development workflow

Run tests:

```bash
python -m unittest discover -s tests
```

Run quality checks:

```bash
ruff check .
mypy src
coverage run -m unittest discover -s tests
coverage report
```

Build and verify artifacts:

```bash
python -m build
python -m twine check dist/*
```

## Notes

- This package is unofficial and not affiliated with Devpost.
- Use responsibly and comply with Devpost and GitHub terms/policies.
