Metadata-Version: 2.4
Name: nexusphp-api
Version: 0.1.3
Summary: NexusPHP API Client - A Python client for interacting with NexusPHP forum API
Home-page: https://github.com/nexusphp/nexusphp_api
Author: LSFXXBJ
Author-email: lsfxxbj@example.com
License: MIT License
Project-URL: Bug Tracker, https://github.com/nexusphp/nexusphp_api/issues
Project-URL: Documentation, https://github.com/nexusphp/nexusphp_api#readme
Project-URL: Source Code, https://github.com/nexusphp/nexusphp_api
Keywords: nexusphp,api,client,torrent,forum
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.28.0
Requires-Dist: typing_extensions>=4.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: flake8>=4.0.0; extra == "dev"
Requires-Dist: black>=22.0.0; extra == "dev"
Requires-Dist: isort>=5.0.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Dynamic: license-file

# NexusPHP API Client

NexusPHP API Client - A Python client for interacting with NexusPHP forum API.

[![PyPI Version](https://img.shields.io/pypi/v/nexusphp-api.svg)](https://pypi.org/project/nexusphp-api/)
[![Python Versions](https://img.shields.io/pypi/pyversions/nexusphp-api.svg)](https://pypi.org/project/nexusphp-api/)
[![License](https://img.shields.io/pypi/l/nexusphp-api.svg)](https://github.com/nexusphp/nexusphp-api/blob/main/LICENSE)

## Project Structure

```
nexusphp_api/
├── api/                 # API data models
│   ├── bookmark/        # Bookmark related
│   ├── comment/         # Comment related
│   ├── section/         # Section related
│   ├── torrent/         # Torrent related
│   └── user/            # User related
├── api_client/          # API client implementation
├── config/              # Configuration management
├── utils/               # Utility functions
├── tests/               # Test code
├── doc/                 # API documentation
├── pyproject.toml       # PEP 517/518 build configuration
├── setup.cfg            # Package metadata and configuration
└── requirements.txt     # Project dependencies
```

## Features

### 1. Bookmark Management
- Add bookmark
- Delete bookmark

### 2. Comment Management
- Get comment list

### 3. Section Management
- Get section information

### 4. Torrent Management
- Get torrent list
- Get torrent detail
- Upload torrent

### 5. User Management
- Get user profile

## Installation

### Install from PyPI (Recommended)

```bash
pip install nexusphp-api
```

### Install from Source

```bash
git clone https://github.com/nexusphp/nexusphp-api.git
cd nexusphp-api
pip install -e .
```

### Install Development Dependencies

```bash
pip install -r requirements.txt
```

## Quick Start

### Basic Usage

```python
from nexusphp_api import NexusAPIClient

# Initialize client
client = NexusAPIClient(
    base_url="https://dev.nexusphp.org",
    token="your-api-token"
)

# Get current user profile
profile = client.profile.get_profile()
print(f"User: {profile.data.data.username}")

# Add bookmark
bookmark = client.bookmark.add_bookmark(torrent_id=123)
print(f"Bookmark status: {bookmark.msg}")

# Delete bookmark
result = client.bookmark.delete_bookmark(torrent_id=123)
print(f"Delete result: {result.msg}")
```

### Dynamic Configuration Update

```python
# Update token
client.set_token("new-token")

# Update base_url
client.set_base_url("https://api.example.com")
```

## Configuration

The project supports configuration via environment variables:

| Environment Variable | Default Value | Description |
|---------------------|---------------|-------------|
| API_BASE_URL | https://api.nexusphp.org | API base URL |
| API_TIMEOUT | 30 | API request timeout (seconds) |
| API_TOKEN | "" | Authentication token |
| LOG_LEVEL | INFO | Log level |
| LOG_FILE | api.log | Log file |
| MAX_RETRIES | 3 | Maximum retry count |
| RETRY_INTERVAL | 1.0 | Retry interval (seconds) |

## API Reference

### NexusAPIClient Main Class

```python
from nexusphp_api import NexusAPIClient

# Initialize
client = NexusAPIClient(
    base_url="https://dev.nexusphp.org",  # Optional, default value
    token="your-token"                    # Optional
)

# Sub-clients
client.profile        # User profile
client.bookmark       # Bookmark management
client.comment        # Comment management
client.section        # Section management
client.torrent        # Torrent management
```

### Available Client Methods

#### ProfileClient (User Profile)
- `get_profile(user_id=None, includes=None, include_fields=None)`

#### BookmarkClient (Bookmark)
- `add_bookmark(torrent_id)`
- `delete_bookmark(torrent_id)`

#### CommentClient (Comment)
- See code and documentation

#### SectionClient (Section)
- See code and documentation

#### TorrentClient (Torrent)
- See code and documentation

## Running Tests

### Run All Tests

```bash
pytest tests/
```

### Run Specific Tests

```bash
pytest tests/test_api_client.py
```

### Run Tests with Coverage

```bash
pytest tests/ --cov=nexusphp_api --cov-report=html
```

### Run with unittest

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

## Code Quality

The project is configured with the following code quality tools:

### Format Code

```bash
black .
isort .
```

### Lint Code

```bash
flake8 .
```

### Type Check

```bash
mypy .
```

## Response Format

All API responses follow this format:

```json
{
  "ret": 0,          // Result code, 0 means success, other means failure
  "msg": "success",  // Text message
  "data": {},        // Response data
  "rid": "uuid",     // Request ID
  "time": 0.123      // Response time (seconds)
}
```

## Utility Functions

The project provides the following utility functions for data conversion and processing:

- `from_str` - String conversion
- `from_int` - Integer conversion
- `from_int_optional` - Optional integer conversion
- `from_float` - Float conversion
- `from_bool` - Boolean conversion
- `from_none` - None conversion
- `from_union` - Union type conversion
- `from_list` - List conversion
- `from_dict` - Dict conversion
- `to_float` - Float output conversion
- `to_class` - Class instance conversion
- `to_enum` - Enum conversion

## Development and Contribution

### Local Development

1. Fork the project repository
2. Clone to local
3. Install development dependencies
4. Create feature branch
5. Commit changes
6. Push to branch
7. Create Pull Request

### Build and Release

```bash
# Build package
python -m build

# Release to PyPI
twine upload dist/*
```

## Notes

1. Make sure you have a valid API token before use
2. Respect API rate limits
3. Check the `ret` field when processing API responses to confirm success
4. Network requests will automatically retry (default 3 times)

## License

MIT License

## Support and Contact

For issues or suggestions, please:
- Submit an Issue: [GitHub Issues](https://github.com/nexusphp/nexusphp-api/issues)
- View documentation: [Project Wiki](https://github.com/nexusphp/nexusphp-api/wiki)
