siteconf
========
Customizes `sys.path` based on platform and Python version when Python loads for site-specific configuration.
This `sitecustomize.py` module plays a crucial role in VFX pipelines by allowing customizations to be applied to the Python environment at startup.
https://docs.python.org/3/library/site.html#module-sitecustomize
## Installation
The easiest way to install is with pip:
```bash
$ pip install siteconf
```
Alternatively, to install from the repo follow these steps:
```bash
$ git clone https://github.com/rsgalloway/siteconf
$ cd siteconf
$ python setup.py install
```
#### distman
Alternate installation using [distman](https://github.com/rsgalloway/distman):
```bash
$ distman [-d]
```
distman will deploy the dist targets defined in the `dist.json` file.
## Usage
The `sitecustomize.py` module provides a convenient way to customize the Python environment by executing code before the interpreter begins executing the main script.
Python libraries are resolved in the following order, from most specific to most agnostic:
$ROOT/$ENV/lib/$PLATFORM/python[$PYVERSION]
$ROOT/$ENV/lib/$PLATFORM/python
$ROOT/$ENV/lib/python[$PYVERSION]
$ROOT/$ENV/lib/python
Some defaults have been set for convenience that can be overridden with [environment variables](#environment-variables).
For example, if `$ROOT` is `/mnt/pipe` and the production environment is `prod`,
then by default on linux `sys.path` would include:
```bash
/mnt/pipe/prod/lib/linux/python3
/mnt/pipe/prod/lib/linux/python
/mnt/pipe/prod/lib/python3
/mnt/pipe/prod/lib/python
```
or on Windows if `$ROOT` is `X:/pipe`:
```shell
X:/pipe/prod/lib/win32/python3
X:/pipe/prod/lib/win32/python
X:/pipe/prod/lib/python3
X:/pipe/prod/lib/python
```
### whichpy
whichpy is the Python equivalent of which: it's a simple command line utility
that tells you the location of Python modules and packages:
```bash
$ whichpy envstack
/mnt/pipe/prod/lib/linux/python/envstack
```
This can be useful when Python modules and packages are contextual and can live
in different places depending on your cwd.
## Environment Variables
The following environment variables can be used to customize Python search paths:
| Variable | Description |
|------------------|-------------|
| $DEFAULT_ENV_DIR | envstack default .env file directory |
| $DEV | add development environment to the search path |
| $DEV_ENV | override the default development environment name "dev" |
| $ENV | add a custom environment to the search path, e.g. "test" |
| $PLATFORM | override the platform name (win32, linux, osx) |
| $PROD_ENV | override the default production environment name "prod" |
| $PYVERSION | Python version (e.g. 2, 3 or 3.11) |
| $ROOT | Python module deployment path including mount point |
## Development Environment
To add development versions of Python libs (supercedes prod):
```bash
$ export DEV=1
```
Now, the dev environment takes precedence over prod, but the prod environment is still in sys.path, just lower down in priority, so anything in dev will override anything else:
```bash
/mnt/pipe/dev/lib/linux/python3
/mnt/pipe/dev/lib/linux/python
/mnt/pipe/dev/lib/python3
/mnt/pipe/dev/lib/python
/mnt/pipe/prod/lib/linux/python3
/mnt/pipe/prod/lib/linux/python
/mnt/pipe/prod/lib/python3
/mnt/pipe/prod/lib/python
```
To add a custom "test" environment to the Python search path (supercedes all others):
$ export ENV="test"
Custom environments can be useful for testing a developer's test environment.
To get an idea how environment variables can be set to customize the Python search path here is an example that includes a custom env "test" and Python version 3.11 on linux:
```bash
$ ENV=test ROOT=/mnt/deploy PYVERSION=3.12 python -m sitecustomize.py
/mnt/deploy/test/lib/linux/python3.12
/mnt/deploy/test/lib/linux/python
/mnt/deploy/test/lib/python3.12
/mnt/deploy/test/lib/python
/mnt/deploy/prod/lib/linux/python3.12
/mnt/deploy/prod/lib/linux/python
/mnt/deploy/prod/lib/python3.12
/mnt/deploy/prod/lib/python
```
## Deployment
A few notes about deployment of Python modules and packages:
- platform agnostic libs should be deployed to `lib`
- platform specific libs should be deployed to `lib/$PLATFORM`
- Python version agnostic libs should be deployed to `python`
- Python version specific libs should be deployed to `python2`, `python3`, `python3.11`, etc.
Raw data
{
"_id": null,
"home_page": "http://github.com/rsgalloway/siteconf",
"name": "siteconf",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": null,
"author": "Ryan Galloway",
"author_email": "ryan@rsgalloway.com",
"download_url": "https://files.pythonhosted.org/packages/44/da/e0449edeb5b04b6b4c8da313cda131aa07a63e1550a559ea4b2cc57e3ebd/siteconf-0.3.0.tar.gz",
"platform": null,
"description": "siteconf\n========\n\nCustomizes `sys.path` based on platform and Python version when Python loads for site-specific configuration.\n\nThis `sitecustomize.py` module plays a crucial role in VFX pipelines by allowing customizations to be applied to the Python environment at startup.\n\nhttps://docs.python.org/3/library/site.html#module-sitecustomize\n\n## Installation\n\nThe easiest way to install is with pip:\n\n```bash\n$ pip install siteconf\n```\n\nAlternatively, to install from the repo follow these steps:\n\n```bash\n$ git clone https://github.com/rsgalloway/siteconf\n$ cd siteconf\n$ python setup.py install\n```\n\n\n#### distman\n\nAlternate installation using [distman](https://github.com/rsgalloway/distman):\n\n```bash\n$ distman [-d]\n```\n\ndistman will deploy the dist targets defined in the `dist.json` file.\n\n## Usage\n\nThe `sitecustomize.py` module provides a convenient way to customize the Python environment by executing code before the interpreter begins executing the main script.\n\nPython libraries are resolved in the following order, from most specific to most agnostic:\n\n $ROOT/$ENV/lib/$PLATFORM/python[$PYVERSION]\n $ROOT/$ENV/lib/$PLATFORM/python\n $ROOT/$ENV/lib/python[$PYVERSION]\n $ROOT/$ENV/lib/python\n\nSome defaults have been set for convenience that can be overridden with [environment variables](#environment-variables).\n\nFor example, if `$ROOT` is `/mnt/pipe` and the production environment is `prod`,\nthen by default on linux `sys.path` would include:\n\n```bash\n/mnt/pipe/prod/lib/linux/python3\n/mnt/pipe/prod/lib/linux/python\n/mnt/pipe/prod/lib/python3\n/mnt/pipe/prod/lib/python\n```\n\nor on Windows if `$ROOT` is `X:/pipe`:\n\n```shell\nX:/pipe/prod/lib/win32/python3\nX:/pipe/prod/lib/win32/python\nX:/pipe/prod/lib/python3\nX:/pipe/prod/lib/python\n```\n\n### whichpy\n\nwhichpy is the Python equivalent of which: it's a simple command line utility\nthat tells you the location of Python modules and packages:\n\n```bash\n$ whichpy envstack\n/mnt/pipe/prod/lib/linux/python/envstack\n```\n\nThis can be useful when Python modules and packages are contextual and can live\nin different places depending on your cwd.\n\n## Environment Variables\n\nThe following environment variables can be used to customize Python search paths:\n\n| Variable | Description |\n|------------------|-------------|\n| $DEFAULT_ENV_DIR | envstack default .env file directory |\n| $DEV | add development environment to the search path |\n| $DEV_ENV | override the default development environment name \"dev\" |\n| $ENV | add a custom environment to the search path, e.g. \"test\" |\n| $PLATFORM | override the platform name (win32, linux, osx) |\n| $PROD_ENV | override the default production environment name \"prod\" |\n| $PYVERSION | Python version (e.g. 2, 3 or 3.11) |\n| $ROOT | Python module deployment path including mount point |\n\n\n## Development Environment\n\nTo add development versions of Python libs (supercedes prod):\n\n```bash\n$ export DEV=1\n```\n\nNow, the dev environment takes precedence over prod, but the prod environment is still in sys.path, just lower down in priority, so anything in dev will override anything else:\n\n```bash\n/mnt/pipe/dev/lib/linux/python3\n/mnt/pipe/dev/lib/linux/python\n/mnt/pipe/dev/lib/python3\n/mnt/pipe/dev/lib/python\n/mnt/pipe/prod/lib/linux/python3\n/mnt/pipe/prod/lib/linux/python\n/mnt/pipe/prod/lib/python3\n/mnt/pipe/prod/lib/python\n```\n\nTo add a custom \"test\" environment to the Python search path (supercedes all others):\n\n $ export ENV=\"test\"\n\nCustom environments can be useful for testing a developer's test environment.\n\nTo get an idea how environment variables can be set to customize the Python search path here is an example that includes a custom env \"test\" and Python version 3.11 on linux:\n\n```bash\n$ ENV=test ROOT=/mnt/deploy PYVERSION=3.12 python -m sitecustomize.py \n/mnt/deploy/test/lib/linux/python3.12\n/mnt/deploy/test/lib/linux/python\n/mnt/deploy/test/lib/python3.12\n/mnt/deploy/test/lib/python\n/mnt/deploy/prod/lib/linux/python3.12\n/mnt/deploy/prod/lib/linux/python\n/mnt/deploy/prod/lib/python3.12\n/mnt/deploy/prod/lib/python\n```\n\n## Deployment\n\nA few notes about deployment of Python modules and packages:\n\n- platform agnostic libs should be deployed to `lib`\n- platform specific libs should be deployed to `lib/$PLATFORM`\n- Python version agnostic libs should be deployed to `python`\n- Python version specific libs should be deployed to `python2`, `python3`, `python3.11`, etc.\n",
"bugtrack_url": null,
"license": null,
"summary": "Configures sys.path to include hierarchical Python paths",
"version": "0.3.0",
"project_urls": {
"Homepage": "http://github.com/rsgalloway/siteconf"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "44dae0449edeb5b04b6b4c8da313cda131aa07a63e1550a559ea4b2cc57e3ebd",
"md5": "c7ac22f68d30751ca3d3b8cab3d363f5",
"sha256": "2b201630fa9a2781049ca1c95af0233cfd6eff24318916d826b166b9d8f2935f"
},
"downloads": -1,
"filename": "siteconf-0.3.0.tar.gz",
"has_sig": false,
"md5_digest": "c7ac22f68d30751ca3d3b8cab3d363f5",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 4490,
"upload_time": "2024-11-11T19:44:52",
"upload_time_iso_8601": "2024-11-11T19:44:52.640324Z",
"url": "https://files.pythonhosted.org/packages/44/da/e0449edeb5b04b6b4c8da313cda131aa07a63e1550a559ea4b2cc57e3ebd/siteconf-0.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-11 19:44:52",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "rsgalloway",
"github_project": "siteconf",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [],
"lcname": "siteconf"
}
JSON
