Merge pull request #13 from PPeitsch/revert-12-docs

Revert "improved docs"

CONTRIBUTING.md

@@ -0,0 +1,36 @@
+# Contributing to BCRA API Connector
+
+We welcome contributions to the BCRA API Connector project! This document provides guidelines for contributing to the project.
+
+## Getting Started
+
+1. Fork the repository on GitHub.
+2. Clone your fork locally.
+3. Create a new branch for your feature or bug fix.
+4. Make your changes and commit them with clear, descriptive commit messages.
+5. Push your changes to your fork on GitHub.
+6. Submit a pull request to the main repository.
+
+## Code Style
+
+- Follow PEP 8 guidelines for Python code.
+- Use meaningful variable and function names.
+- Write clear comments and docstrings.
+
+## Testing
+
+- Add tests for new features or bug fixes.
+- Ensure all tests pass before submitting a pull request.
+
+## Reporting Issues
+
+- Use the GitHub issue tracker to report bugs or suggest features.
+- Provide as much detail as possible, including steps to reproduce for bugs.
+
+## Pull Requests
+
+- Clearly describe the problem and solution in the PR description.
+- Include any relevant issue numbers.
+- Keep PRs focused on a single change rather than multiple unrelated changes.
+
+Thank you for contributing to BCRA API Connector!

README.md

@@ -55,25 +55,21 @@ print(f"Latest value for Variable {id_variable}: {latest.valor} ({latest.fecha})
 
 ## Documentation
 
-For detailed documentation, please visit our [Read The Docs Documentation](https://bcra-connector.readthedocs.io/).
+For detailed documentation, including usage examples and API reference, please visit our [Read The Docs Documentation](https://bcra-connector.readthedocs.io/).
 
 ## Contributing
 
-Contributions are welcome! We encourage you to submit a Pull Request.
+Contributions are welcome! Please read our [Contributing Guidelines](CONTRIBUTING.md) for details on how to submit pull requests, report issues, and suggest improvements.
 
 ## License
 
 This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
 
 ## Changelog
 
-For a detailed list of changes and version updates, please refer to the [CHANGELOG.rst](CHANGELOG.rst) file.
-
-## Version History
-
-- 0.1.0 (2024-08-23): Initial release
-- 0.1.1 (2024-08-29): Updated dependencies to address security vulnerabilities
+For a detailed list of changes and version updates, please refer to the [Changelog](https://bcra-connector.readthedocs.io/en/latest/changelog.html).
 
 ## Disclaimer
 
 This project is not officially affiliated with or endorsed by the Banco Central de la República Argentina. Use at your own risk.
+

docs/source/api_reference.rst

@@ -15,6 +15,8 @@ The main class for interacting with the BCRA API.
 - `verify_ssl` (bool, optional): Whether to verify SSL certificates. Default is True.
 - `debug` (bool, optional): Enable debug logging. Default is False.
 
+**Note:** Disabling SSL verification (`verify_ssl=False`) is not recommended in production environments as it may expose your application to security risks. Only use this option in development environments or when dealing with self-signed certificates.
+
 ### Methods
 
 ```{py:method} get_principales_variables()
@@ -28,6 +30,20 @@ List[PrincipalesVariables]: A list of principal variables.
 **Raises:**
 BCRAApiError: If the API request fails.
 
+**Example response:**
+```python
+[
+    PrincipalesVariables(
+        id_variable=1,
+        cd_serie=246,
+        descripcion="Reservas Internacionales del BCRA",
+        fecha="2024-09-07",
+        valor=27755.0
+    ),
+    # ... more variables
+]
+```
+
 ---
 
 ```{py:method} get_datos_variable(id_variable: int, desde: datetime, hasta: datetime)
@@ -37,8 +53,8 @@ Fetch historical data for a specific variable within a date range.
 
 **Parameters:**
 - `id_variable` (int): The ID of the desired variable.
-- `desde` (datetime): The start date of the range to query.
-- `hasta` (datetime): The end date of the range to query.
+- `desde` (datetime): The start date of the range to query (inclusive).
+- `hasta` (datetime): The end date of the range to query (inclusive).
 
 **Returns:**
 List[DatosVariable]: A list of historical data points.
@@ -47,6 +63,8 @@ List[DatosVariable]: A list of historical data points.
 - BCRAApiError: If the API request fails.
 - ValueError: If the date range is invalid.
 
+**Note:** Dates should be provided as Python `datetime` objects. The API uses the date format "YYYY-MM-DD" internally.
+
 ---
 
 ```{py:method} get_latest_value(id_variable: int)
@@ -63,6 +81,8 @@ DatosVariable: The latest data point for the specified variable.
 **Raises:**
 BCRAApiError: If the API request fails or if no data is available.
 
+**Note:** The BCRA typically updates data daily, but update frequency may vary by variable. Check the `fecha` field in the response for the exact date of the latest value.
+
 ## Data Classes
 
 ### PrincipalesVariables
@@ -76,7 +96,7 @@ Represents a principal variable from the BCRA API.
 - `id_variable` (int): The ID of the variable.
 - `cd_serie` (int): The series code of the variable.
 - `descripcion` (str): The description of the variable.
-- `fecha` (str): The date of the variable's value.
+- `fecha` (str): The date of the variable's value (format: "YYYY-MM-DD").
 - `valor` (float): The value of the variable.
 
 ### DatosVariable
@@ -88,7 +108,7 @@ Represents historical data for a variable.
 
 **Attributes:**
 - `id_variable` (int): The ID of the variable.
-- `fecha` (str): The date of the data point.
+- `fecha` (str): The date of the data point (format: "YYYY-MM-DD", timezone: ART - Argentina Time).
 - `valor` (float): The value of the variable on the given date.
 
 ## Exceptions
@@ -102,10 +122,15 @@ Custom exception for BCRA API errors.
 
 This exception is raised when an API request fails, either due to network issues, authentication problems, or invalid data.
 
+Common error scenarios:
+- 400 Bad Request: Invalid parameters or date range
+- 404 Not Found: Requested resource not available
+- 500 Internal Server Error: BCRA API server issues
+
 ## Constants
 
 - `BASE_URL`: The base URL for the BCRA API.
-- `MAX_RETRIES`: Maximum number of retry attempts for failed requests.
-- `RETRY_DELAY`: Initial delay (in seconds) between retry attempts.
+- `MAX_RETRIES` (default: 3): Maximum number of retry attempts for failed requests.
+- `RETRY_DELAY` (default: 1): Initial delay (in seconds) between retry attempts.
 
 This API reference provides a comprehensive overview of the BCRA API Connector's functionality. For usage examples and best practices, refer to the [Usage Guide](usage.rst) and [Examples](examples.rst) sections.

docs/source/changelog.rst

@@ -5,29 +5,27 @@ All notable changes to the BCRA API Connector will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [0.2.0] - 2024-09-07
 
 ### Added
-- Support for new BCRA API endpoints (planned for future release)
-
-### Changed
-- Improved error messages for better debugging (in progress)
-
-## [0.2.0] - 2024-09-15
-
-### Added
-- New `get_latest_value()` method for quick access to current data
-- Debug mode for detailed logging
 - Comprehensive documentation with usage examples and API reference
+- Debug mode for detailed logging
 
 ### Changed
 - Improved error handling with custom `BCRAApiError` exception
 - Enhanced retry logic with exponential backoff
+- Improved documentation clarity and structure
+- Updated README with more comprehensive information
 
 ### Fixed
 - SSL verification issues in certain environments
 
-## [0.1.0] - 2024-08-25
+## [0.1.1] - 2024-08-29
+
+### Changed
+- Updated dependencies to address security vulnerabilities
+
+## [0.1.0] - 2024-08-23
 
 ### Added
 - Initial release of the BCRA API Connector
@@ -47,14 +45,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Basic API documentation
 - Installation guide
 
-## [0.0.1] - 2024-07-10
-
-### Added
-- Project initialization
-- Basic project structure
-- Initial implementation of API connection
-
-[Unreleased]: https://github.com/yourusername/bcra-api-connector/compare/v0.2.0...HEAD
-[0.2.0]: https://github.com/yourusername/bcra-api-connector/compare/v0.1.0...v0.2.0
-[0.1.0]: https://github.com/yourusername/bcra-api-connector/compare/v0.0.1...v0.1.0
-[0.0.1]: https://github.com/yourusername/bcra-api-connector/releases/tag/v0.0.1
+[0.2.0]: https://github.com/yourusername/bcra-api-connector/compare/v0.1.1...v0.2.0
+[0.1.1]: https://github.com/yourusername/bcra-api-connector/compare/v0.1.0...v0.1.1
+[0.1.0]: https://github.com/yourusername/bcra-api-connector/releases/tag/v0.1.0

docs/source/conf.py

@@ -6,11 +6,11 @@
 
 # -- Project information -----------------------------------------------------
 project = 'BCRA API Connector'
-copyright = '2024, Your Name'
-author = 'Your Name'
+copyright = '2024, Pablo Peitsch'
+author = 'Pablo Peitsch'
 
 # The full version, including alpha/beta/rc tags
-release = '0.1.0'
+release = '0.2.0'
 
 # -- General configuration ---------------------------------------------------
 extensions = [

docs/source/configuration.rst

@@ -1,92 +1,73 @@
-# Configuring the BCRA API Connector
+Configuration
+=============
 
-The BCRA API Connector offers various configuration options to tailor its behavior to your specific needs. This guide explains each option in detail and provides examples of when and how to use them.
+The BCRA API Connector offers several configuration options to customize its behavior. This guide explains each option and how to use it.
 
-## Initialization Options
+Initialization Options
+----------------------
 
-When creating a new instance of `BCRAConnector`, you can customize its behavior using the following parameters:
+When creating a new instance of the `BCRAConnector`, you can pass the following parameters:
 
-```python
-from bcra_connector import BCRAConnector
+.. code-block:: python
 
-connector = BCRAConnector(
-    language="es-AR",
-    verify_ssl=True,
-    debug=False
-)
-```
+   connector = BCRAConnector(
+       language="es-AR",
+       verify_ssl=True,
+       debug=False
+   )
 
-### Language Setting
+Language
+~~~~~~~~
 
-The `language` parameter determines the language for API responses.
+The `language` parameter sets the language for API responses. Available options are:
 
-- **Options**: 
-  - `"es-AR"` (default): Spanish (Argentina)
-  - `"en-US"`: English (United States)
+- `"es-AR"` (default): Spanish (Argentina)
+- `"en-US"`: English (United States)
 
-**Example:**
-```python
-connector = BCRAConnector(language="en-US")
-```
+Example:
 
-**Use case:** Set to "en-US" if you prefer English responses or are building an English-language application.
+.. code-block:: python
 
-### SSL Verification
+   connector = BCRAConnector(language="en-US")
 
-The `verify_ssl` parameter controls whether SSL certificates are verified during API requests.
+SSL Verification
+~~~~~~~~~~~~~~~~
 
-- **Options**:
-  - `True` (default): Verify SSL certificates
-  - `False`: Disable SSL verification
+The `verify_ssl` parameter determines whether SSL certificates should be verified during API requests. By default, it's set to `True`.
 
-**Example:**
-```python
-connector = BCRAConnector(verify_ssl=False)
-```
+To disable SSL verification (not recommended for production):
 
-**Warning:** Disabling SSL verification is not recommended for production use as it may expose you to security risks.
+.. code-block:: python
 
-**Use case:** Temporarily disable during development if encountering SSL-related issues, or when working in environments with self-signed certificates.
+   connector = BCRAConnector(verify_ssl=False)
 
-### Debug Mode
+Debug Mode
+~~~~~~~~~~
 
-The `debug` parameter enables detailed logging for troubleshooting.
+The `debug` parameter enables detailed logging when set to `True`. This is useful for troubleshooting.
 
-- **Options**:
-  - `False` (default): Normal logging
-  - `True`: Verbose debug logging
+Example:
 
-**Example:**
-```python
-connector = BCRAConnector(debug=True)
-```
+.. code-block:: python
 
-**Use case:** Enable when you need to diagnose issues or want to understand the connector's internal operations.
+   connector = BCRAConnector(debug=True)
 
-## Advanced Configuration
+Retry Behavior
+--------------
 
-For more advanced use cases, you can modify the connector's retry behavior by subclassing `BCRAConnector`:
-
-```python
-class CustomBCRAConnector(BCRAConnector):
-    MAX_RETRIES = 5
-    RETRY_DELAY = 2
-
-connector = CustomBCRAConnector()
-```
-
-### Retry Mechanism
+The connector implements a retry mechanism with exponential backoff. You can modify this behavior by changing the following class variables:
 
 - `MAX_RETRIES`: Maximum number of retry attempts (default: 3)
 - `RETRY_DELAY`: Initial delay between retries in seconds (default: 1)
 
-**Use case:** Increase `MAX_RETRIES` and `RETRY_DELAY` when working with unstable network connections or during high-traffic periods.
+To change these values, subclass `BCRAConnector`:
+
+.. code-block:: python
 
-## Best Practices
+   class CustomBCRAConnector(BCRAConnector):
+       MAX_RETRIES = 5
+       RETRY_DELAY = 2
 
-1. **Production Settings:** Always use SSL verification in production environments.
-2. **Localization:** Choose the appropriate language setting based on your target audience.
-3. **Debugging:** Use debug mode sparingly, as it can generate large log files.
-4. **Retry Tuning:** Adjust retry settings based on your specific use case and the API's behavior.
+   connector = CustomBCRAConnector()
 
-By leveraging these configuration options, you can optimize the BCRA API Connector's performance and reliability for your specific use case.
+This configuration provides more flexibility and control over the connector's behavior.