Metadata-Version: 2.4
Name: sqlalchemy-config
Version: 0.4.7b0
Summary: Handle sqlalchemy connection params in a config file.
Author-email: Chris Finan <c.finan@ucl.ac.uk>
License-Expression: GPL-3.0-or-later
Project-URL: Homepage, https://gitlab.com/cfinan/sqlalchemy-config
Project-URL: Documentation, https://cfinan.gitlab.io/sqlalchemy-config/index.html
Project-URL: Repository, https://gitlab.com/cfinan/sqlalchemy-config
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: <3.14,>=3.11
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: cfin-pyaddons
Requires-Dist: numpydoc
Requires-Dist: sqlalchemy>=2
Requires-Dist: sqlalchemy-utils>=0.37.8
Requires-Dist: stdopen
Requires-Dist: tqdm
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Dynamic: license-file

# Getting Started with sqlalchemy-config

__version__: `0.4.7b0`

The sqlalchemy-config package is a toolkit to handle database configuration parameters that are stored in a config file. This can locate, read, and extract the config parameters and create a sessionmaker object from them that is bound to the engine object.

There is [online](https://cfinan.gitlab.io/sqlalchemy-config/index.html) documentation for sqlalchemy-config.

## Installation instructions
sqlalchemy-config can be installed via pypi or conda.

### Installation using pip

```
pip install sqlalchemy-config
```

### Installation using conda
I maintain a conda package in my personal conda channel. To install this please run:

```
conda install -c cfin -c conda-forge sqlalchemy-config
```

## Usage TL;DR
sqlalchemy-config is designed to handle database connection inputs coming from different sources. For example: a URL or SQLite file path on the command line, a config file path from a command-line argument, an environment variable, or a default file in the home directory.

The config files used in the example below have a similar structure to this see [SQLAlchemy engine from config](https://docs.sqlalchemy.org/en/13/core/engines.html#sqlalchemy.engine_from_config):


```
[mydb_mysql]
# Make sure this is only readable by you
# Make sure password is URL encoded, see: sqlalchemy_config.encode_password
db.url = mysql+pymysql://user:password@127.0.0.1:3306/db_cfg_arg
```

```python
>>> import sqlalchemy_config as sqlc
>>> import os

>>> # Input from the command line (SQLite file path)
>>> dbarg = "mydb.db"

>>> # Prefix used for SQLAlchemy parameters in config sections
>>> conn_prefix = "db."

>>> # This represents a default location for config files containing parameters
>>> config_file = os.path.join(os.environ['HOME'], "mydbs_def.cnf")

>>> # dbarg is treated as SQLite file path
>>> sqlc.get_new_sessionmaker(dbarg, conn_prefix=conn_prefix, config_arg=config_file)
>>> sessionmaker(class_='Session', bind=Engine(sqlite:///mydb.db), autoflush=True, autocommit=False, expire_on_commit=True)

>>> # dbarg can also be a fully formed SQLAlchemy URL
>>> dbarg = "mysql+pymysql://user:password@127.0.0.1:3306/db_url_arg"
>>> sqlc.get_new_sessionmaker(dbarg)
>>> sessionmaker(class_='Session', bind=Engine(mysql+pymysql://user:***@127.0.0.1:3306/db_url_arg), autoflush=True, autocommit=False, expire_on_commit=True)
```

See the API documentation for lower level functions.

## Development

To set up a development environment, install the package with development dependencies:

```bash
pip install -e ".[dev]"
```

Run the test suite:

```bash
pytest tests/ -v
```

Run tests with coverage reporting:

```bash
pytest --cov=sqlalchemy_config --cov-report=term-missing tests/
```

Verify the coverage threshold (80%) is met:

```bash
pytest --cov=sqlalchemy_config --cov-fail-under=80 tests/
```

Lint and format code before committing:

```bash
ruff check --fix . && ruff format .
```

## Change log

See [CHANGELOG.md](CHANGELOG.md) for the full change log.
