Pathao Python SDK - Quick Start Guide

How to Use These Documents with Agentic AI Coding Tools

📚 Document Overview

You now have 4 comprehensive documents for developing the Pathao Python SDK:

1. pathao_srs.md - Software Requirements Specification

When to use: To understand project scope, requirements, and architecture
For AI: Reference when requesting full feature implementations
Key sections:
- Functional Requirements (FR-3.1 through FR-3.6)
- Non-functional Requirements (performance, security, etc.)
- System Architecture diagrams
- Data Models specifications
- Success criteria

2. pathao_api_docs.md - API Documentation

When to use: To understand the public API interface and expected behavior
For AI: Provide to AI when requesting client implementation
Key sections:
- Complete API reference for all classes and methods
- Data model definitions (dataclasses)
- Exception handling
- Usage examples
- Error handling patterns

3. pathao_dev_guide.md - Development Guide

When to use: Step-by-step implementation guidance
For AI: Your primary reference during development
Key sections:
- Phase-by-phase implementation breakdown
- File-by-file specifications
- Code patterns and examples
- Testing strategy
- CI/CD setup

4. pathao_implementation_checklist.md - Implementation Checklist

When to use: Track progress and ensure nothing is missed
For AI: Use to verify completeness before moving to next phase
Key sections:
- Checkbox items for every component
- Test coverage requirements
- Quality metrics
- Release checklist

🚀 Getting Started with AI Code Generation

Step 1: Prepare Your Environment

# Clone the repository
git clone https://github.com/yourusername/pathao-python.git
cd pathao-python

# Install dependencies
pip install -r requirements.txt
pip install -r requirements-dev.txt

# Copy environment template
cp .env.example .env
# Edit .env with your Pathao credentials

Step 2: Use AI Code Generation Effectively

Strategy A: Module-by-Module Generation

For each module, follow this pattern:

Human: "Generate the [MODULE_NAME] module for the Pathao SDK.

Use the specifications from pathao_dev_guide.md Phase [X].

The module should:
- Implement class: [ClassName]
- With methods: [list methods with signatures]
- Raise exceptions: [list exception types]
- Follow the patterns in: [reference existing module]
- Include full docstrings
- Add type hints for all parameters

Here are the models it should use:
[paste relevant model definitions from pathao_api_docs.md]

Expected behavior example:
[paste usage example from pathao_api_docs.md]"

Strategy B: Implementation with Tests

Human: "Generate [file.py] and test_[file].py simultaneously.

From pathao_dev_guide.md Phase [X], implement:
[list what to implement]

Include:
1. Production code with full docstrings
2. Comprehensive tests covering:
   - Happy path
   - Validation errors
   - API errors
   - Edge cases

Use these fixtures:
[paste fixture definitions]

Test coverage target: [X]%"

Strategy C: Batch Generation

For creating multiple related files:

Human: "Generate the entire [SUBSYSTEM] (files: auth.py, store.py, order.py)

Requirements from pathao_dev_guide.md Phases 4-6:
[list requirements]

All modules should:
- Import from models.py and exceptions.py
- Use http_client.HTTPClient
- Follow the pattern shown in [reference]

Here are the shared models:
[paste model definitions]

Here's the base structure example:
[paste reference implementation]"

📋 Typical Development Workflow

Week 1: Core Infrastructure

Generate Phase 1 Setup (configuration files)
- Reference: pathao_dev_guide.md → Phase 1
- Checklist: pathao_implementation_checklist.md → Phase 1
Generate Phase 2 Core (exceptions, models, validators)
- Reference: pathao_dev_guide.md → Phase 2
- Include test generation
- Checklist: pathao_implementation_checklist.md → Phase 2
Generate Phase 3 HTTP Client
- Reference: pathao_dev_guide.md → Phase 3
- Include retry logic tests
- Checklist: pathao_implementation_checklist.md → Phase 3

Week 2-3: API Modules

Generate Phase 4-9 (Auth, Store, Order, Location, Price modules)
- One module per AI request
- Reference: pathao_dev_guide.md → Phase [X]
- Include comprehensive tests
- Checklist: Track in pathao_implementation_checklist.md → Phase [X]

Week 4: Integration

Generate Phase 10 (Main Client)
- Reference: pathao_dev_guide.md → Phase 10
- Integration tests
- Checklist: pathao_implementation_checklist.md → Phase 10
Generate Phase 11 (Package Init)
- Reference: pathao_dev_guide.md → Phase 11
- Ensure proper exports
- Checklist: pathao_implementation_checklist.md → Phase 11

Week 5: Testing & Documentation

Generate remaining tests
- Reference: pathao_implementation_checklist.md → Phase 11
- Target: 80%+ coverage
Generate documentation examples
- Reference: pathao_api_docs.md → Examples section
- Create example scripts
Generate CI/CD files
- Reference: pathao_dev_guide.md → CI/CD Configuration
- GitHub Actions workflows

💡 Tips for Best Results with AI

1. Provide Complete Context

Instead of:

"Generate the AuthModule"

Do:

"From pathao_dev_guide.md Phase 4.1, generate the AuthModule class.

It should:
- Handle OAuth 2.0 authentication
- Manage access tokens with auto-refresh
- Use the AuthToken dataclass defined in models.py
- Raise AuthenticationError on failures

Here's the class signature:

class AuthModule:
    def __init__(self, http_client: HTTPClient, credentials: dict)
    def get_access_token(self) -> str
    def refresh_token(self) -> AuthToken
    # ... other methods

Use this HTTP client pattern:
[show example]

Here's the expected behavior:
[paste from API docs]"

2. Reference Specific Sections

Always cite the exact phase/section from the documents:

pathao_srs.md → Section X.Y
pathao_dev_guide.md → Phase X.Y
pathao_api_docs.md → API Reference section
pathao_implementation_checklist.md → Phase X

3. Include Test Requirements

Always specify test expectations:

"Generate with tests that cover:
- Valid input handling
- Input validation errors (list specific validations)
- API error responses
- Network timeouts
- Edge cases: [list specific cases]

Target coverage: 85%+"

4. Use Fixtures Effectively

When generating code that uses fixtures:

"Use the following fixtures from conftest.py:
[paste fixture definitions]

Mock responses from mock_responses.py:
[paste relevant mock response]"

5. Build Incrementally

Don't ask for everything at once. Build in phases:

Phase 1: Exceptions and Models
Phase 2: Validators and Utilities
Phase 3: HTTP Client (one of most complex)
Phase 4: Single module to establish pattern
Phase 5-8: Remaining modules (easier now that pattern is established)
Phase 9-10: Integration layers

🔄 Review and Iteration Process

After Each Generation:

Review Generated Code

# Check code style
black --check pathao/
flake8 pathao/
mypy pathao/

Run Tests
```
pytest tests/ -v --cov=pathao
```
Verify Against Requirements
- Check SRS requirements are met
- Verify API docs match implementation
- Update checklist

Request Improvements If code needs changes, provide specific feedback:

"The generate [Module] is almost right, but:

1. The [method] should [specific requirement]
2. The error handling for [scenario] should [what to do]
3. Add validation for [parameter] checking [constraint]

Here's what it should do:
[paste from docs]"

📊 Quality Gates

Before proceeding to next phase, ensure:

All code passes black formatter
No flake8 linting errors
All mypy type checks pass
Tests pass: pytest --tb=short
Coverage meets target: pytest --cov=pathao
Docstrings complete and accurate
No hardcoded values or credentials
Error messages are clear and helpful

🎯 Key Prompts for Common Tasks

Generate a Module

"From [pathao_dev_guide.md → Phase X.Y], generate the [ModuleName] class.

Include:
1. Class definition with __init__ and all methods listed in [section]
2. Full docstrings (Args, Returns, Raises, Examples)
3. Type hints throughout
4. Error handling as specified in [section]
5. Logging of important operations

Methods to implement:
[list all methods with signatures]

Exception handling:
- Raise [Exception1] when [condition]
- Raise [Exception2] when [condition]

Usage example from pathao_api_docs.md:
[paste relevant example]"

Generate Tests for a Module

"Generate comprehensive tests for [Module] (tests/test_[module].py)

Test patterns from pathao_dev_guide.md Phase 11.2:
- Unit tests with fixtures
- Mock HTTP responses
- Error scenario tests

Required test coverage:
- [method1]: [scenarios to test]
- [method2]: [scenarios to test]
- [method3]: [scenarios to test]

Fixtures to use:
[paste fixture definitions from conftest.py]

Mock responses:
[paste mock response examples]

Target coverage: 85%+"

Generate Documentation Example

"Generate an example script (examples/[name].py) showing how to:
1. [Use case 1]
2. [Use case 2]
3. Handle errors during [operation]

Requirements from pathao_api_docs.md:
- Include this code pattern: [example from docs]
- Handle these exceptions: [list exceptions]
- Show best practices for: [list best practices]

The example should be:
- Fully runnable with valid .env credentials
- Well-commented with explanations
- Show both success and error cases"

📞 Quick Reference Commands

# Format code
black pathao/ tests/

# Check formatting
black --check pathao/ tests/

# Lint code
flake8 pathao/ tests/

# Type check
mypy pathao/

# Run tests
pytest tests/ -v

# Run tests with coverage
pytest tests/ --cov=pathao --cov-report=html

# Run specific test
pytest tests/test_auth.py -v

# Install package in development mode
pip install -e .

# Build package
python -m build

# Check package structure
python -m twine check dist/*

🚨 Common Issues and Solutions

Issue: Generated code doesn't match API docs

Solution: Provide the exact API signature from pathao_api_docs.md in your prompt

Issue: Tests are too comprehensive

Solution: Specify exactly which scenarios to test: "Test happy path, validation errors, and API errors only"

Issue: Missing docstrings or type hints

Solution: Explicitly request: "Include full docstrings in Google format. Add type hints for all parameters."

Issue: Code doesn't follow project patterns

Solution: Provide reference implementation: "Follow the pattern shown in [existing_module]"

Issue: Coverage is too low

Solution: Request specific test additions: "Add tests for these uncovered scenarios: [list]"

Sign-Off Checklist

Before publishing to PyPI, ensure:

📖 Additional Resources

Pathao Official API Docs: https://pathao.com/api-docs
Python SDK Best Practices: https://docs.python-guide.org/
PyPI Packaging Guide: https://packaging.python.org/
GitHub Actions Guide: https://docs.github.com/en/actions
Type Hints Guide: https://docs.python.org/3/library/typing.html

🤝 Next Steps

Set up your development environment
- Create GitHub repository
- Clone locally
- Create .env file with credentials
Start with Phase 1
- Generate configuration files
- Setup initial package structure
- Commit to repository
Generate core infrastructure (Phase 2-3)
- Exceptions and models
- Validators and utilities
- HTTP client
Build modules incrementally (Phase 4-9)
- One module at a time
- Include tests for each
- Verify against checklist
Integration and testing (Phase 10-12)
- Main client class
- Package initialization
- Additional tests
Documentation and release (Phase 13-17)
- Documentation
- CI/CD setup
- Release to PyPI

You're ready to build! Start with Phase 1 in pathao_dev_guide.md

Good luck with your Pathao Python SDK project! 🎉

FilesExpand file tree

QUICK_START.md

Latest commit

History