Metadata-Version: 2.4
Name: apig
Version: 0.1.0
Summary: Generic API Gateway framework for building flexible API clients
Author: Maintainers
Author-email: solubrew@solutionsbrewer.com
License: MIT
Platform: Linux
Requires-Python: >=3.10
Requires-Dist: click>=8.0
Requires-Dist: requests>=2.28
Requires-Dist: aiohttp>=3.8
Requires-Dist: pandas>=2.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: logma>=0.1
Requires-Dist: kahndor>=0.1
Requires-Dist: pytest>=7.0 ; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21 ; extra == "dev"
Requires-Dist: ruff>=0.1 ; extra == "dev"
Requires-Dist: black>=23.0 ; extra == "dev"
Requires-Dist: mypy>=1.0 ; extra == "dev"
Provides-Extra: dev
Description: # 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.
Description-Content-Type: text/markdown
