| Name | paramlib JSON |
| Version |
3.4.10
JSON |
| download |
| home_page | None |
| Summary | A Python library for managing configuration parameters and constants, centralizing access to application-wide settings and global constants |
| upload_time | 2025-07-17 11:20:27 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.10 |
| license | MIT License
Copyright (c) 2024 ParamLib
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE. |
| keywords |
configuration
parameters
constants
settings
global variables
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
numpy
pandas
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# paramlib
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
[](https://pypi.org/project/paramlib/)
**paramlib** is a centralised Python library for global parameter management and configuration constants. It provides a comprehensive collection of standardised parameters, format strings, and configuration templates commonly used across scientific computing, data processing, and application development projects. The library emphasises consistency, maintainability, and ease of access to frequently used constants and configuration patterns.
## Features
- **Global Parameter Management**:
- Centralised storage of frequently used constants and parameters
- Standardised naming conventions following Python best practices
- Organised parameter categories for easy navigation and maintenance
- Version-controlled parameter definitions with change tracking
- **Time-Related Parameters**:
- Comprehensive time format strings (basic, non-standard, and custom)
- Month mappings and seasonal frequency dictionaries
- Date unit conversions and mathematical time constants
- Support for various time representations and calculations
- **Mathematical and Programming Concepts**:
- Basic arithmetic operators and set operations
- Regular expression patterns for common validation tasks
- File system and storage entity type definitions
- Common delimiter collections for string processing
- **Configuration Management**:
- Database credential templates and error code mappings
- User information management paths and structures
- Socio-economical and climate science parameter collections
- Standardised configuration patterns for various domains
## Installation
### Prerequisites
Before installing, please ensure the following dependencies are available on your system:
- **External Tools** (required for full functionality):
- No external tools required (pure Python library)
- **Required Third-Party Libraries**:
```bash
pip install pandas numpy
```
Or via Anaconda (recommended channel: `conda-forge`):
```bash
conda install -c conda-forge pandas numpy
```
- **Internal Package Dependencies**:
```bash
pip install filewise
pip install pygenutils # Core functionality
pip install pygenutils[arrow] # With arrow support (optional)
```
### For regular users (from PyPI)
```bash
pip install paramlib
```
### For contributors/developers (with latest Git versions)
```bash
# Install with development dependencies (includes latest Git versions)
pip install -e .[dev]
# Alternative: Use requirements-dev.txt for explicit Git dependencies
pip install -r requirements-dev.txt
pip install -e .
```
**Benefits of the new approach:**
- **Regular users**: Simple `pip install paramlib` with all dependencies included
- **Developers**: Access to latest Git versions for development and testing
- **PyPI compatibility**: All packages can be published without Git dependency issues
**If you encounter import errors:**
1. **For PyPI users**: The package should install all dependencies automatically. If you get import errors, try:
```bash
pip install --upgrade paramlib
```
2. **For developers**: Make sure you've installed the development dependencies:
```bash
pip install -e .[dev]
```
3. **Common issues**:
- **Missing dependencies**: For regular users, all dependencies are included. For developers, use `pip install -e .[dev]`
- **Python version**: Ensure you're using Python 3.10 or higher
- **Pure Python library**: No external system dependencies required
### Verify Installation
To verify that your installation is working correctly:
```python
try:
import paramlib
from paramlib.global_parameters import COMMON_DELIMITER_LIST, BASIC_TIME_FORMAT_STRS
from paramlib.config_params import DATABASE_CREDENTIALS
print("✅ All imports successful!")
print(f"✅ paramlib version: {paramlib.__version__}")
print("✅ Installation is working correctly.")
except ImportError as e:
print(f"❌ Import error: {e}")
print("💡 For regular users: pip install paramlib")
print("💡 For developers: pip install -e .[dev]")
```
## Usage
### Basic Global Parameters Access
```python
from paramlib.global_parameters import (
BASIC_TIME_FORMAT_STRS,
COMMON_DELIMITER_LIST,
BASIC_ARITHMETIC_OPERATORS
)
# Access time format strings
datetime_format = BASIC_TIME_FORMAT_STRS["H"] # "%F %T"
date_only_format = BASIC_TIME_FORMAT_STRS["D"] # "%F"
# Use common delimiters
delimiter = COMMON_DELIMITER_LIST[0] # "_"
csv_delimiter = COMMON_DELIMITER_LIST[4] # ","
# Mathematical operators
operators = BASIC_ARITHMETIC_OPERATORS # ["+", "-", "*", "/"]
```
### Configuration Parameters
```python
from paramlib.config_params import (
DATABASE_CREDENTIALS,
DB_ERROR_CODE_DICT,
USER_INFO_JSON_PATH
)
# Database configuration template
db_config = DATABASE_CREDENTIALS.copy()
db_config.update({
"username": "myuser",
"password": "mypassword",
"host": "localhost",
"port": "5432",
"database_name": "mydb"
})
# Handle database errors
error_code = "1045"
if error_code in DB_ERROR_CODE_DICT:
print(f"Database error: {DB_ERROR_CODE_DICT[error_code]}")
# Output: "Database error: Wrong username"
# User information file path
user_file = USER_INFO_JSON_PATH # "users.json"
```
### Advanced Time Handling
```python
from paramlib.global_parameters import (
NON_STANDARD_TIME_FORMAT_STRS,
CUSTOM_TIME_FORMAT_STRS,
MONTH_NUMBER_DICT,
SEASON_TIME_FREQ_DICT
)
# Non-standard time formats
ctime_format = NON_STANDARD_TIME_FORMAT_STRS["CTIME_H"] # "%a %b %d %T %Y"
# Custom Excel-compatible formats
excel_format = CUSTOM_TIME_FORMAT_STRS["CT_EXCEL_SPANISH_D"] # "%d/%m/%y"
# Month and season mappings
month_letter = MONTH_NUMBER_DICT[3] # "M" (March)
spring_freq = SEASON_TIME_FREQ_DICT[3] # "Q-MAR"
```
### Scientific and Climate Data Parameters
```python
from paramlib.global_parameters import (
EMISSION_RCP_SCENARIOS,
CLIMATE_FILE_EXTENSIONS,
MATHEMATICAL_YEAR_DAYS
)
# Climate change scenarios
scenarios = EMISSION_RCP_SCENARIOS # ["historical", "rcp26", "rcp45", "rcp85"]
# Supported climate file formats
extensions = CLIMATE_FILE_EXTENSIONS # ["nc", "grib", "netcdf_zip", "csv"]
# Mathematical approximations
year_days = MATHEMATICAL_YEAR_DAYS # 360 (for simplified calculations)
```
### Regular Expressions and Validation
```python
from paramlib.global_parameters import PASSWORD_REGEX_PATTERN
import re
# Password validation
password = "MySecure123!"
if re.match(PASSWORD_REGEX_PATTERN, password):
print("Password meets security requirements")
# The pattern validates:
# - Minimum 8 characters
# - At least one lowercase letter
# - At least one uppercase letter
# - At least one digit
# - At least one special character
```
### Data Processing Utilities
```python
from paramlib.global_parameters import (
PANDAS_DATE_UNIT_LIST,
NUMPY_DATE_UNIT_LIST,
UNIT_FACTOR_DICT,
TIME_FREQUENCIES_COMPLETE
)
# Date unit handling for pandas/numpy
pandas_units = PANDAS_DATE_UNIT_LIST # ['D', 'ms', 'ns', 's', 'us']
numpy_units = NUMPY_DATE_UNIT_LIST # ['Y', 'M', 'D', 'h', 'm', 's', 'ms', 'us', 'ns']
# Unit conversions
ms_factor = UNIT_FACTOR_DICT["ms"] # 1e-3
# Time frequency options
frequencies = TIME_FREQUENCIES_COMPLETE
# ["year", "season", "month", "day", "hour", "minute", "second"]
```
## Project Structure
The package is organised as a focused parameter management library:
```text
paramlib/
├── global_parameters.py # Global constants and parameters
├── config_params.py # Configuration templates and mappings
├── __init__.py # Package initialisation
├── CHANGELOG.md # Version history and parameter updates
└── README.md # Package documentation
```
## Parameter Categories
### 1. Time-Related Parameters
- **Basic Time Formats**: Standard datetime format strings for common use cases
- **Non-Standard Formats**: Alternative time representations (ctime, etc.)
- **Custom Formats**: Specialised formats for Excel, regional settings
- **Month Mappings**: Numeric to letter conversions and seasonal frequencies
- **Date Units**: Pandas and NumPy compatible unit specifications
### 2. Mathematical Concepts
- **Arithmetic Operators**: Basic mathematical operation symbols
- **Set Operations**: Set algebra operation names and definitions
- **Mathematical Constants**: Approximations and standard values
### 3. Programming Concepts
- **File System**: Module names and entity type definitions
- **Regular Expressions**: Common validation patterns
- **String Processing**: Standard delimiter collections
- **Data Types**: Storage and processing type definitions
### 4. Configuration Management
- **Database Credentials**: Template structure for database connections
- **Error Mappings**: Common database error codes and descriptions
- **File Paths**: Standard configuration file locations
### 5. Socio-Economical Concepts
- **Climate Science**: RCP scenarios and file format specifications
- **Data Standards**: Common file extensions and format definitions
## Key Constants Reference
### Time Format Strings
```python
BASIC_TIME_FORMAT_STRS = {
"H": "%F %T", # Full datetime
"D": "%F", # Date only
"M": "%Y-%m", # Year-month
"Y": "%Y" # Year only
}
```
### Common Delimiters
```python
COMMON_DELIMITER_LIST = ["_", "-", ";", ":", ",", "\n", "\t", " "]
```
### Database Configuration
```python
DATABASE_CREDENTIALS = {
"username": "username",
"password": "cool-password",
"host": "host",
"port": "port",
"database_name": "dbname"
}
```
### Climate Science Parameters
```python
EMISSION_RCP_SCENARIOS = ["historical", "rcp26", "rcp45", "rcp85"]
CLIMATE_FILE_EXTENSIONS = ["nc", "grib", "netcdf_zip", "csv"]
```
## Naming Conventions
The library follows strict Python naming conventions:
- **Constants**: All uppercase with underscores (e.g., `BASIC_TIME_FORMAT_STRS`)
- **Dictionaries**: Descriptive names ending with appropriate suffixes (`_DICT`, `_LIST`, etc.)
- **Keys**: Descriptive, abbreviated where appropriate, consistent across similar structures
- **Values**: Standardised formats following industry best practices
## Integration Examples
### With Pandas DataFrames
```python
from paramlib.global_parameters import BASIC_TIME_FORMAT_STRS, PANDAS_DATE_UNIT_LIST
import pandas as pd
# Create datetime index with standard format
date_format = BASIC_TIME_FORMAT_STRS["H"]
df = pd.DataFrame({
'timestamp': pd.to_datetime(['2023-01-01 12:00:00'], format=date_format),
'value': [100]
})
# Use standard date units
df['timestamp'] = pd.to_datetime(df['timestamp'], unit=PANDAS_DATE_UNIT_LIST[0])
```
### With Configuration Management
```python
from paramlib.config_params import DATABASE_CREDENTIALS, DB_ERROR_CODE_DICT
import sqlalchemy
def create_database_connection():
try:
# Use template for connection
conn_str = f"postgresql://{DATABASE_CREDENTIALS['username']}:{DATABASE_CREDENTIALS['password']}@{DATABASE_CREDENTIALS['host']}:{DATABASE_CREDENTIALS['port']}/{DATABASE_CREDENTIALS['database_name']}"
engine = sqlalchemy.create_engine(conn_str)
return engine
except Exception as e:
error_code = str(e.args[0])
if error_code in DB_ERROR_CODE_DICT:
print(f"Connection failed: {DB_ERROR_CODE_DICT[error_code]}")
raise
```
### With Climate Data Processing
```python
from paramlib.global_parameters import EMISSION_RCP_SCENARIOS, CLIMATE_FILE_EXTENSIONS
def process_climate_files(directory_path):
"""Process climate data files based on standard scenarios and formats."""
valid_scenarios = EMISSION_RCP_SCENARIOS
valid_extensions = CLIMATE_FILE_EXTENSIONS
for scenario in valid_scenarios:
for ext in valid_extensions:
file_pattern = f"*{scenario}*.{ext}"
# Process files matching pattern
print(f"Processing {scenario} files with extension {ext}")
```
## Best Practices
### Parameter Usage
- Import only the parameters you need to avoid namespace pollution
- Use descriptive variable names when assigning parameter values
- Document parameter usage in your code for maintainability
- Follow the established naming conventions when extending parameters
### Configuration Management
- Always copy dictionary templates before modifying them
- Validate parameter values before using them in production code
- Use the provided error mappings for consistent error handling
- Keep configuration separate from business logic
### Version Compatibility
- Check the changelog when updating to new versions
- Test parameter-dependent code when upgrading
- Use version pinning for production deployments
- Document parameter dependencies in your project requirements
## System Requirements
- **Python**: 3.10 or higher
- **Dependencies**: pandas and numpy (optional, for enhanced functionality)
- **Memory**: Minimal (constants are loaded on import)
- **Performance**: Instant access to all parameters
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request for:
- New parameter categories or constants
- Improved naming conventions
- Additional configuration templates
- Documentation enhancements
### Development Guidelines
1. **Follow naming conventions**: All constants must be uppercase with descriptive names
2. **Maintain organisation**: Add new parameters to appropriate categories
3. **Document changes**: Update CHANGELOG.md with parameter additions/modifications
4. **Test compatibility**: Ensure changes don't break existing parameter usage
5. **Provide examples**: Include usage examples for new parameter categories
```bash
git clone https://github.com/yourusername/paramlib.git
cd paramlib
pip install -e .
```
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Acknowledgments
- **Python Community** for establishing naming convention standards
- **Scientific Computing Community** for parameter standardisation requirements
- **Open Source Contributors** for feedback and parameter suggestions
- **Data Science Community** for real-world usage patterns and requirements
## Contact
For questions or suggestions, please open an issue on GitHub or contact the maintainers.
## Troubleshooting
### Common Issues
1. **Import Errors**:
```python
# Correct import
from paramlib.global_parameters import BASIC_TIME_FORMAT_STRS
# Avoid importing everything
# from paramlib.global_parameters import * # Not recommended
```
2. **Parameter Modification**:
```python
# Safe parameter usage
from paramlib.config_params import DATABASE_CREDENTIALS
# Always copy before modifying
my_config = DATABASE_CREDENTIALS.copy()
my_config["username"] = "myuser"
```
3. **Version Compatibility**:
```python
# Check parameter availability
from paramlib.global_parameters import BASIC_TIME_FORMAT_STRS
if "H_NO_DATE_SEP" in BASIC_TIME_FORMAT_STRS:
format_str = BASIC_TIME_FORMAT_STRS["H_NO_DATE_SEP"]
```
### Getting Help
- Check the [CHANGELOG.md](CHANGELOG.md) for parameter updates
- Review parameter definitions in the source code
- Open an issue on GitHub for missing parameters or suggestions
- Consult the examples section for usage patterns
Raw data
{
"_id": null,
"home_page": null,
"name": "paramlib",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "configuration, parameters, constants, settings, global variables",
"author": null,
"author_email": "Jon Ander Gabantxo <jagabantxo@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/22/54/64900c0b4233fff4143a3adfed7ac776f22befa4f1c755e4b7a3ffc9b7dd/paramlib-3.4.10.tar.gz",
"platform": null,
"description": "# paramlib\n\n[](https://www.python.org/downloads/)\n[](https://opensource.org/licenses/MIT)\n[](https://pypi.org/project/paramlib/)\n\n**paramlib** is a centralised Python library for global parameter management and configuration constants. It provides a comprehensive collection of standardised parameters, format strings, and configuration templates commonly used across scientific computing, data processing, and application development projects. The library emphasises consistency, maintainability, and ease of access to frequently used constants and configuration patterns.\n\n## Features\n\n- **Global Parameter Management**:\n - Centralised storage of frequently used constants and parameters\n - Standardised naming conventions following Python best practices\n - Organised parameter categories for easy navigation and maintenance\n - Version-controlled parameter definitions with change tracking\n\n- **Time-Related Parameters**:\n - Comprehensive time format strings (basic, non-standard, and custom)\n - Month mappings and seasonal frequency dictionaries\n - Date unit conversions and mathematical time constants\n - Support for various time representations and calculations\n\n- **Mathematical and Programming Concepts**:\n - Basic arithmetic operators and set operations\n - Regular expression patterns for common validation tasks\n - File system and storage entity type definitions\n - Common delimiter collections for string processing\n\n- **Configuration Management**:\n - Database credential templates and error code mappings\n - User information management paths and structures\n - Socio-economical and climate science parameter collections\n - Standardised configuration patterns for various domains\n\n## Installation\n\n### Prerequisites\n\nBefore installing, please ensure the following dependencies are available on your system:\n\n- **External Tools** (required for full functionality):\n - No external tools required (pure Python library)\n\n- **Required Third-Party Libraries**:\n\n ```bash\n pip install pandas numpy\n ```\n\n Or via Anaconda (recommended channel: `conda-forge`):\n\n ```bash\n conda install -c conda-forge pandas numpy\n ```\n\n- **Internal Package Dependencies**:\n\n ```bash\n pip install filewise\n pip install pygenutils # Core functionality\n pip install pygenutils[arrow] # With arrow support (optional)\n ```\n\n### For regular users (from PyPI)\n\n```bash\npip install paramlib\n```\n\n### For contributors/developers (with latest Git versions)\n\n```bash\n# Install with development dependencies (includes latest Git versions)\npip install -e .[dev]\n\n# Alternative: Use requirements-dev.txt for explicit Git dependencies\npip install -r requirements-dev.txt\npip install -e .\n```\n\n**Benefits of the new approach:**\n\n- **Regular users**: Simple `pip install paramlib` with all dependencies included\n- **Developers**: Access to latest Git versions for development and testing\n- **PyPI compatibility**: All packages can be published without Git dependency issues\n\n**If you encounter import errors:**\n\n1. **For PyPI users**: The package should install all dependencies automatically. If you get import errors, try:\n\n ```bash\n pip install --upgrade paramlib\n ```\n\n2. **For developers**: Make sure you've installed the development dependencies:\n\n ```bash\n pip install -e .[dev]\n ```\n\n3. **Common issues**:\n - **Missing dependencies**: For regular users, all dependencies are included. For developers, use `pip install -e .[dev]`\n - **Python version**: Ensure you're using Python 3.10 or higher\n - **Pure Python library**: No external system dependencies required\n\n### Verify Installation\n\nTo verify that your installation is working correctly:\n\n```python\ntry:\n import paramlib\n from paramlib.global_parameters import COMMON_DELIMITER_LIST, BASIC_TIME_FORMAT_STRS\n from paramlib.config_params import DATABASE_CREDENTIALS\n \n print(\"\u2705 All imports successful!\")\n print(f\"\u2705 paramlib version: {paramlib.__version__}\")\n print(\"\u2705 Installation is working correctly.\")\n \nexcept ImportError as e:\n print(f\"\u274c Import error: {e}\")\n print(\"\ud83d\udca1 For regular users: pip install paramlib\")\n print(\"\ud83d\udca1 For developers: pip install -e .[dev]\")\n```\n\n## Usage\n\n### Basic Global Parameters Access\n\n```python\nfrom paramlib.global_parameters import (\n BASIC_TIME_FORMAT_STRS,\n COMMON_DELIMITER_LIST,\n BASIC_ARITHMETIC_OPERATORS\n)\n\n# Access time format strings\ndatetime_format = BASIC_TIME_FORMAT_STRS[\"H\"] # \"%F %T\"\ndate_only_format = BASIC_TIME_FORMAT_STRS[\"D\"] # \"%F\"\n\n# Use common delimiters\ndelimiter = COMMON_DELIMITER_LIST[0] # \"_\"\ncsv_delimiter = COMMON_DELIMITER_LIST[4] # \",\"\n\n# Mathematical operators\noperators = BASIC_ARITHMETIC_OPERATORS # [\"+\", \"-\", \"*\", \"/\"]\n```\n\n### Configuration Parameters\n\n```python\nfrom paramlib.config_params import (\n DATABASE_CREDENTIALS,\n DB_ERROR_CODE_DICT,\n USER_INFO_JSON_PATH\n)\n\n# Database configuration template\ndb_config = DATABASE_CREDENTIALS.copy()\ndb_config.update({\n \"username\": \"myuser\",\n \"password\": \"mypassword\",\n \"host\": \"localhost\",\n \"port\": \"5432\",\n \"database_name\": \"mydb\"\n})\n\n# Handle database errors\nerror_code = \"1045\"\nif error_code in DB_ERROR_CODE_DICT:\n print(f\"Database error: {DB_ERROR_CODE_DICT[error_code]}\")\n # Output: \"Database error: Wrong username\"\n\n# User information file path\nuser_file = USER_INFO_JSON_PATH # \"users.json\"\n```\n\n### Advanced Time Handling\n\n```python\nfrom paramlib.global_parameters import (\n NON_STANDARD_TIME_FORMAT_STRS,\n CUSTOM_TIME_FORMAT_STRS,\n MONTH_NUMBER_DICT,\n SEASON_TIME_FREQ_DICT\n)\n\n# Non-standard time formats\nctime_format = NON_STANDARD_TIME_FORMAT_STRS[\"CTIME_H\"] # \"%a %b %d %T %Y\"\n\n# Custom Excel-compatible formats\nexcel_format = CUSTOM_TIME_FORMAT_STRS[\"CT_EXCEL_SPANISH_D\"] # \"%d/%m/%y\"\n\n# Month and season mappings\nmonth_letter = MONTH_NUMBER_DICT[3] # \"M\" (March)\nspring_freq = SEASON_TIME_FREQ_DICT[3] # \"Q-MAR\"\n```\n\n### Scientific and Climate Data Parameters\n\n```python\nfrom paramlib.global_parameters import (\n EMISSION_RCP_SCENARIOS,\n CLIMATE_FILE_EXTENSIONS,\n MATHEMATICAL_YEAR_DAYS\n)\n\n# Climate change scenarios\nscenarios = EMISSION_RCP_SCENARIOS # [\"historical\", \"rcp26\", \"rcp45\", \"rcp85\"]\n\n# Supported climate file formats\nextensions = CLIMATE_FILE_EXTENSIONS # [\"nc\", \"grib\", \"netcdf_zip\", \"csv\"]\n\n# Mathematical approximations\nyear_days = MATHEMATICAL_YEAR_DAYS # 360 (for simplified calculations)\n```\n\n### Regular Expressions and Validation\n\n```python\nfrom paramlib.global_parameters import PASSWORD_REGEX_PATTERN\nimport re\n\n# Password validation\npassword = \"MySecure123!\"\nif re.match(PASSWORD_REGEX_PATTERN, password):\n print(\"Password meets security requirements\")\n\n# The pattern validates:\n# - Minimum 8 characters\n# - At least one lowercase letter\n# - At least one uppercase letter\n# - At least one digit\n# - At least one special character\n```\n\n### Data Processing Utilities\n\n```python\nfrom paramlib.global_parameters import (\n PANDAS_DATE_UNIT_LIST,\n NUMPY_DATE_UNIT_LIST,\n UNIT_FACTOR_DICT,\n TIME_FREQUENCIES_COMPLETE\n)\n\n# Date unit handling for pandas/numpy\npandas_units = PANDAS_DATE_UNIT_LIST # ['D', 'ms', 'ns', 's', 'us']\nnumpy_units = NUMPY_DATE_UNIT_LIST # ['Y', 'M', 'D', 'h', 'm', 's', 'ms', 'us', 'ns']\n\n# Unit conversions\nms_factor = UNIT_FACTOR_DICT[\"ms\"] # 1e-3\n\n# Time frequency options\nfrequencies = TIME_FREQUENCIES_COMPLETE\n# [\"year\", \"season\", \"month\", \"day\", \"hour\", \"minute\", \"second\"]\n```\n\n## Project Structure\n\nThe package is organised as a focused parameter management library:\n\n```text\nparamlib/\n\u251c\u2500\u2500 global_parameters.py # Global constants and parameters\n\u251c\u2500\u2500 config_params.py # Configuration templates and mappings\n\u251c\u2500\u2500 __init__.py # Package initialisation\n\u251c\u2500\u2500 CHANGELOG.md # Version history and parameter updates\n\u2514\u2500\u2500 README.md # Package documentation\n```\n\n## Parameter Categories\n\n### 1. Time-Related Parameters\n\n- **Basic Time Formats**: Standard datetime format strings for common use cases\n- **Non-Standard Formats**: Alternative time representations (ctime, etc.)\n- **Custom Formats**: Specialised formats for Excel, regional settings\n- **Month Mappings**: Numeric to letter conversions and seasonal frequencies\n- **Date Units**: Pandas and NumPy compatible unit specifications\n\n### 2. Mathematical Concepts\n\n- **Arithmetic Operators**: Basic mathematical operation symbols\n- **Set Operations**: Set algebra operation names and definitions\n- **Mathematical Constants**: Approximations and standard values\n\n### 3. Programming Concepts\n\n- **File System**: Module names and entity type definitions\n- **Regular Expressions**: Common validation patterns\n- **String Processing**: Standard delimiter collections\n- **Data Types**: Storage and processing type definitions\n\n### 4. Configuration Management\n\n- **Database Credentials**: Template structure for database connections\n- **Error Mappings**: Common database error codes and descriptions\n- **File Paths**: Standard configuration file locations\n\n### 5. Socio-Economical Concepts\n\n- **Climate Science**: RCP scenarios and file format specifications\n- **Data Standards**: Common file extensions and format definitions\n\n## Key Constants Reference\n\n### Time Format Strings\n\n```python\nBASIC_TIME_FORMAT_STRS = {\n \"H\": \"%F %T\", # Full datetime\n \"D\": \"%F\", # Date only\n \"M\": \"%Y-%m\", # Year-month\n \"Y\": \"%Y\" # Year only\n}\n```\n\n### Common Delimiters\n\n```python\nCOMMON_DELIMITER_LIST = [\"_\", \"-\", \";\", \":\", \",\", \"\\n\", \"\\t\", \" \"]\n```\n\n### Database Configuration\n\n```python\nDATABASE_CREDENTIALS = {\n \"username\": \"username\",\n \"password\": \"cool-password\",\n \"host\": \"host\",\n \"port\": \"port\",\n \"database_name\": \"dbname\"\n}\n```\n\n### Climate Science Parameters\n\n```python\nEMISSION_RCP_SCENARIOS = [\"historical\", \"rcp26\", \"rcp45\", \"rcp85\"]\nCLIMATE_FILE_EXTENSIONS = [\"nc\", \"grib\", \"netcdf_zip\", \"csv\"]\n```\n\n## Naming Conventions\n\nThe library follows strict Python naming conventions:\n\n- **Constants**: All uppercase with underscores (e.g., `BASIC_TIME_FORMAT_STRS`)\n- **Dictionaries**: Descriptive names ending with appropriate suffixes (`_DICT`, `_LIST`, etc.)\n- **Keys**: Descriptive, abbreviated where appropriate, consistent across similar structures\n- **Values**: Standardised formats following industry best practices\n\n## Integration Examples\n\n### With Pandas DataFrames\n\n```python\nfrom paramlib.global_parameters import BASIC_TIME_FORMAT_STRS, PANDAS_DATE_UNIT_LIST\nimport pandas as pd\n\n# Create datetime index with standard format\ndate_format = BASIC_TIME_FORMAT_STRS[\"H\"]\ndf = pd.DataFrame({\n 'timestamp': pd.to_datetime(['2023-01-01 12:00:00'], format=date_format),\n 'value': [100]\n})\n\n# Use standard date units\ndf['timestamp'] = pd.to_datetime(df['timestamp'], unit=PANDAS_DATE_UNIT_LIST[0])\n```\n\n### With Configuration Management\n\n```python\nfrom paramlib.config_params import DATABASE_CREDENTIALS, DB_ERROR_CODE_DICT\nimport sqlalchemy\n\ndef create_database_connection():\n try:\n # Use template for connection\n conn_str = f\"postgresql://{DATABASE_CREDENTIALS['username']}:{DATABASE_CREDENTIALS['password']}@{DATABASE_CREDENTIALS['host']}:{DATABASE_CREDENTIALS['port']}/{DATABASE_CREDENTIALS['database_name']}\"\n engine = sqlalchemy.create_engine(conn_str)\n return engine\n except Exception as e:\n error_code = str(e.args[0])\n if error_code in DB_ERROR_CODE_DICT:\n print(f\"Connection failed: {DB_ERROR_CODE_DICT[error_code]}\")\n raise\n```\n\n### With Climate Data Processing\n\n```python\nfrom paramlib.global_parameters import EMISSION_RCP_SCENARIOS, CLIMATE_FILE_EXTENSIONS\n\ndef process_climate_files(directory_path):\n \"\"\"Process climate data files based on standard scenarios and formats.\"\"\"\n valid_scenarios = EMISSION_RCP_SCENARIOS\n valid_extensions = CLIMATE_FILE_EXTENSIONS\n \n for scenario in valid_scenarios:\n for ext in valid_extensions:\n file_pattern = f\"*{scenario}*.{ext}\"\n # Process files matching pattern\n print(f\"Processing {scenario} files with extension {ext}\")\n```\n\n## Best Practices\n\n### Parameter Usage\n\n- Import only the parameters you need to avoid namespace pollution\n- Use descriptive variable names when assigning parameter values\n- Document parameter usage in your code for maintainability\n- Follow the established naming conventions when extending parameters\n\n### Configuration Management\n\n- Always copy dictionary templates before modifying them\n- Validate parameter values before using them in production code\n- Use the provided error mappings for consistent error handling\n- Keep configuration separate from business logic\n\n### Version Compatibility\n\n- Check the changelog when updating to new versions\n- Test parameter-dependent code when upgrading\n- Use version pinning for production deployments\n- Document parameter dependencies in your project requirements\n\n## System Requirements\n\n- **Python**: 3.10 or higher\n- **Dependencies**: pandas and numpy (optional, for enhanced functionality)\n- **Memory**: Minimal (constants are loaded on import)\n- **Performance**: Instant access to all parameters\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request for:\n\n- New parameter categories or constants\n- Improved naming conventions\n- Additional configuration templates\n- Documentation enhancements\n\n### Development Guidelines\n\n1. **Follow naming conventions**: All constants must be uppercase with descriptive names\n2. **Maintain organisation**: Add new parameters to appropriate categories\n3. **Document changes**: Update CHANGELOG.md with parameter additions/modifications\n4. **Test compatibility**: Ensure changes don't break existing parameter usage\n5. **Provide examples**: Include usage examples for new parameter categories\n\n```bash\ngit clone https://github.com/yourusername/paramlib.git\ncd paramlib\npip install -e .\n```\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Acknowledgments\n\n- **Python Community** for establishing naming convention standards\n- **Scientific Computing Community** for parameter standardisation requirements\n- **Open Source Contributors** for feedback and parameter suggestions\n- **Data Science Community** for real-world usage patterns and requirements\n\n## Contact\n\nFor questions or suggestions, please open an issue on GitHub or contact the maintainers.\n\n## Troubleshooting\n\n### Common Issues\n\n1. **Import Errors**:\n\n ```python\n # Correct import\n from paramlib.global_parameters import BASIC_TIME_FORMAT_STRS\n \n # Avoid importing everything\n # from paramlib.global_parameters import * # Not recommended\n ```\n\n2. **Parameter Modification**:\n\n ```python\n # Safe parameter usage\n from paramlib.config_params import DATABASE_CREDENTIALS\n \n # Always copy before modifying\n my_config = DATABASE_CREDENTIALS.copy()\n my_config[\"username\"] = \"myuser\"\n ```\n\n3. **Version Compatibility**:\n\n ```python\n # Check parameter availability\n from paramlib.global_parameters import BASIC_TIME_FORMAT_STRS\n \n if \"H_NO_DATE_SEP\" in BASIC_TIME_FORMAT_STRS:\n format_str = BASIC_TIME_FORMAT_STRS[\"H_NO_DATE_SEP\"]\n ```\n\n### Getting Help\n\n- Check the [CHANGELOG.md](CHANGELOG.md) for parameter updates\n- Review parameter definitions in the source code\n- Open an issue on GitHub for missing parameters or suggestions\n- Consult the examples section for usage patterns\n",
"bugtrack_url": null,
"license": "MIT License\n \n Copyright (c) 2024 ParamLib\n \n Permission is hereby granted, free of charge, to any person obtaining a copy\n of this software and associated documentation files (the \"Software\"), to deal\n in the Software without restriction, including without limitation the rights\n to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n copies of the Software, and to permit persons to whom the Software is\n furnished to do so, subject to the following conditions:\n \n The above copyright notice and this permission notice shall be included in all\n copies or substantial portions of the Software.\n \n THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n SOFTWARE. ",
"summary": "A Python library for managing configuration parameters and constants, centralizing access to application-wide settings and global constants",
"version": "3.4.10",
"project_urls": {
"Bug Reports": "https://github.com/EusDancerDev/paramlib/issues",
"Documentation": "https://github.com/EusDancerDev/paramlib#readme",
"Homepage": "https://github.com/EusDancerDev/paramlib",
"Repository": "https://github.com/EusDancerDev/paramlib.git"
},
"split_keywords": [
"configuration",
" parameters",
" constants",
" settings",
" global variables"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "d21db8e1f4745d1bbc690a8b0f231da0a6161d027781e157531478625c355312",
"md5": "4ec219ea2e1b9dcc26c91501cd79739f",
"sha256": "de57d03e7cfdc356b89165640ff8724c643137c0571232f753402a540dd78311"
},
"downloads": -1,
"filename": "paramlib-3.4.10-py3-none-any.whl",
"has_sig": false,
"md5_digest": "4ec219ea2e1b9dcc26c91501cd79739f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 10995,
"upload_time": "2025-07-17T11:20:26",
"upload_time_iso_8601": "2025-07-17T11:20:26.124974Z",
"url": "https://files.pythonhosted.org/packages/d2/1d/b8e1f4745d1bbc690a8b0f231da0a6161d027781e157531478625c355312/paramlib-3.4.10-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "225464900c0b4233fff4143a3adfed7ac776f22befa4f1c755e4b7a3ffc9b7dd",
"md5": "d5f087c1f7acca85237e4b6473fbfcec",
"sha256": "b32c5ea08f0679cfede6ccd9a7730cd69efe66aa41a5129f6b4a4f31ea95a9ab"
},
"downloads": -1,
"filename": "paramlib-3.4.10.tar.gz",
"has_sig": false,
"md5_digest": "d5f087c1f7acca85237e4b6473fbfcec",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 11713,
"upload_time": "2025-07-17T11:20:27",
"upload_time_iso_8601": "2025-07-17T11:20:27.218177Z",
"url": "https://files.pythonhosted.org/packages/22/54/64900c0b4233fff4143a3adfed7ac776f22befa4f1c755e4b7a3ffc9b7dd/paramlib-3.4.10.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-17 11:20:27",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "EusDancerDev",
"github_project": "paramlib",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "numpy",
"specs": [
[
">=",
"1.21.0"
]
]
},
{
"name": "pandas",
"specs": [
[
">=",
"1.3.0"
]
]
}
],
"lcname": "paramlib"
}
