APig

    APig is a Python module that consumes data from arbitrary APIs using a YAML-based interface mapping. It provides a declarative way to define API endpoints, request methods, parameters, authentication, and response parsing in YAML files, allowing seamless interaction with any HTTP-based API through a unified Python interface. This eliminates the need for custom code per API, making it ideal for integration, data fetching, and automation tasks.
    
    ## Features
    
    - **YAML-Based Interface Mapping**: Define API structures, endpoints, authentication, and parsing rules in simple YAML configurations.
    - **Arbitrary API Support**: Compatible with RESTful APIs, GraphQL, SOAP, or any HTTP protocol, with support for GET, POST, PUT, DELETE, etc.
    - **Data Consumption and Parsing**: Automatically fetch, parse, and return data in formats like JSON, XML, or custom structures.
    - **Authentication Handling**: Built-in support for API keys, Bearer tokens, OAuth, basic auth, and custom headers via YAML.
    - **Parameter Management**: Handle query params, body data, path variables, and dynamic substitutions.
    - **Error Handling and Retries**: Configurable retries, timeouts, and validation for robust API interactions.
    - **Extensible**: Add custom request hooks, response processors, or parsers.
    - **Cross-Platform Compatibility**: Works on Windows, macOS, and Linux.
    
    ## Installation
    
    You can install APig via pip:
    
    ```bash
    pip install apig
    ```
    
    Alternatively, clone the repository and install from source:
    
    ```bash
    git clone https://github.com/<USER_OR_ORG>/apig.git
    cd apig
    pip install -e .
    ```
    
    ### Requirements
    
    - Python 3.12 or higher
    - Dependencies: requests, pyyaml, <PARSE_LIB> (automatically installed via pip where applicable)
    
    ## Quick Start
    
    Import the module, load a YAML configuration, and consume data from an API:
    
    ```python
    import apig
    
    # Load YAML config for the API
    config = apig.load_config('path/to/api.yaml')
    
    # Initialize APig with the config
    api = apig.APig(config)
    
    # Call an endpoint
    response = api.call('get_user', params={'id': 123})
    print(response)  # Parsed data, e.g., {'name': 'John Doe', ...}
    ```
    
    ## Usage
    
    ### Loading Configurations
    
    APig relies on YAML files to map API interfaces. A sample YAML might look like:
    
    ```yaml
    api_base: https://api.example.com
    auth:
      type: api_key
      key: <API_KEY>
      placement: header
      header_name: X-Api-Key
    endpoints:
      get_user:
        path: /users/{id}
        method: GET
        params:
          - name: id
            type: path
        response:
          format: json
          parse: .data.user
    ```
    
    Use `apig.load_config(yaml_path)` to parse and validate the config.
    
    ### Calling APIs
    
    ```python
    # Initialize with config
    config = apig.load_config('weather_api.yaml')
    api = apig.APig(config)
    
    # Call with parameters
    weather = api.call('forecast', params={'city': 'London', 'days': 5})
    
    # Handle POST requests
    api.call('create_post', body={'title': 'New Post', 'content': 'Hello World'})
    ```
    
    ### Handling Responses
    
    Responses are automatically parsed based on YAML rules:
    
    ```python
    # Get raw response if needed
    raw = api.call('endpoint', return_raw=True)
    
    # Custom parsing override
    parsed = api.parse_response(raw, custom_parser=lambda x: x['custom_field'])
    ```
    
    ## Examples
    
    ### Example 1: Fetching Data from a Public API
    
    ```python
    import apig
    
    config = apig.load_config('public_api.yaml')
    api = apig.APig(config)
    data = api.call('random_fact')
    print(data)  # e.g., {'fact': 'A random interesting fact.'}
    ```
    
    ### Example 2: Authenticated API with Parameters
    
    ```python
    import apig
    
    config = apig.load_config('secure_api.yaml')
    api = apig.APig(config)
    user_profile = api.call('profile', params={'user_id': 456}, auth_override={'token': 'new_token'})
    print(user_profile)
    ```
    
    ## Configuration Guide
    
    Each YAML config must include:
    
    - `api_base`: Base URL for the API
    - `auth`: Dictionary for authentication details (type, key, etc.)
    - `endpoints`: Mapping of endpoint names to details (path, method, params, response)
    - `defaults`: Optional global settings like headers, timeouts
    
    For advanced customization, refer to the [docs/config-reference.md](docs/config-reference.md).
    
    ## Contributing
    
    Contributions are welcome! Please follow these steps:
    
    1. Fork the repository.
    2. Create a feature branch (`git checkout -b feature/<FEATURE_NAME>`).
    3. Commit your changes (`git commit -am 'Add some feature'`).
    4. Push to the branch (`git push origin feature/<FEATURE_NAME>`).
    5. Open a Pull Request.
    
    See [CONTRIBUTING.md](CONTRIBUTING.md) for more details.
    
    ## License
    
    This project is licensed under the <LICENSE_TYPE> License - see the [LICENSE](LICENSE) file for details.
    
    ## Acknowledgments
    
    - Built with inspiration from open-source API client communities.
    - Thanks to contributors of underlying libraries like requests, pyyaml.