# bw_matchbox
[][pypi status]
[][pypi status]
<!-- [][pypi status] -->
[][license]
<!-- [][read the docs] -->
<!-- [][tests] -->
<!-- [][codecov] -->
<!-- [][pre-commit] -->
<!-- [][black] -->
[pypi status]: https://pypi.org/project/bw_matchbox/
[read the docs]: https://bw_matchbox.readthedocs.io/
[tests]: https://github.com/cauldron/bw_matchbox/actions?workflow=Tests
[codecov]: https://app.codecov.io/gh/cauldron/bw_matchbox
[pre-commit]: https://github.com/pre-commit/pre-commit
[black]: https://github.com/psf/black
`bw_matchbox` is a web app for matching two [Brightway](https://docs.brightway.dev/en/latest/). It allows you to do complicated matches, such as:
* Link process a to processes b and c, with allocation factors
* Link process a to a proxy for process b, changing the exchange values in b proxy to match those in process a where desired
* Link process a to a proxy for process b, removing some exchanges from b and adding some from a
* Link process a to a proxy for process b, expanding and inlining some exchanges from b to "flatten" its supply chain
## Installation
You can install _bw_matchbox_ via [pip] from [PyPI]:
```console
pip install bw_matchbox
```
It's possible to install the library itself for development purposes (in the cloned project):
```console
pip install -e .
```
This library depends on:
* Brightway 2.5 (`brightway25`)
* `docopt-ng`
* `flask` and `flask_httpauth`
* `tomli`
* `werkzeug`
## Usage
This is a `flask` application. Flask has a debug server suitable for development, but it [should not be used for production](https://flask.palletsprojects.com/en/2.3.x/deploying/)!
To use `bw_matchbox`, you need to do the following:
### Create a configuration file
Configuration is done via a `toml` file. See [`config_example.toml`](https://github.com/cauldron/bw_matchbox/blob/main/config_example.toml) for the structure of this file. Here is an example:
```toml
[users]
jane = "deer"
john = "doe"
[roles]
editors = ["jane"]
reviewers = ["john"]
[configs]
my_config = { project = "something", source = "database A", target = "database B", proxy = "database C"}
[files]
output_dir = "/Path/to/some/directory"
```
The `config.toml` file needs to provide the following:
* `[users]` section: Authentication, via a set of usernames and passwords
* `[roles]` section: The exact role labels must be used. Editors can make changes, reviewers can only comment.
* `[configs]` section: A combination of Brightway project and the source, target and proxy databases.
* `[files]` section: Currently only uses the `output_dir` key.
The easiest way to set this up is with:
```console
matchbox setup
```
This will create stub configuration and changes files in your current working directory - note that you should change the configuration and username/password in `config.toml`.
### Running the development server
Just run:
```console
matchbox webapp config.toml
```
### Running in production
You will need to configure the Flask app using `configure_app`, or re-implement its functionality. Here is an example using [waitress](https://docs.pylonsproject.org/projects/waitress/en/stable/index.html):
```python
from bw_matchbox import matchbox_app, configure_app
config_filepath = "/path/to/config.toml"
app = configure_app(config_filepath, matchbox_app)
from waitress import serve
serve(app, port=8080)
```
### Starting the app
Once the app is running and configured locally or remotely, connect to the correct address and port. If you are running locally, this is probably either `http://localhost:5000` or `http://127.0.0.1:5000`.
In the first screen, choose the Brightway project you want to work on. This is `matchbox-example` if you ran `matchbox example_project`.
On the next screen, choose one database as the *source*, and **a different database** as the *target*. Currently you need to specify a new proxy database by typing a new database name into the *Create a new database* input box.
## Contributing
Contributions are very welcome.
To learn more, see the [Contributor Guide].
## License
Distributed under the terms of the [MIT license][license],
_bw_matchbox_ is free and open source software.
## Issues
If you encounter any problems,
please [file an issue] along with a detailed description.
<!-- github-only -->
[command-line reference]: https://bw_matchbox.readthedocs.io/en/latest/usage.html
[license]: https://github.com/cauldron/bw_matchbox/blob/main/LICENSE
[contributor guide]: https://github.com/cauldron/bw_matchbox/blob/main/CONTRIBUTING.md
Raw data
{
"_id": null,
"home_page": "https://github.com/cauldron/bw_matchbox",
"name": "bw-matchbox",
"maintainer": "Chris Mutel",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "<cmutel@gmail.com>",
"keywords": "\"brightway\",\"development\"",
"author": "Chris Mutel",
"author_email": "<cmutel@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/85/0f/caac8d494f5fe3396cf28c1975ad109ca5244a77d0a50c360dfe4faf94a4/bw_matchbox-2.6.tar.gz",
"platform": "any",
"description": "# bw_matchbox\n\n[][pypi status]\n[][pypi status]\n<!-- [][pypi status] -->\n[][license]\n\n<!-- [][read the docs] -->\n<!-- [][tests] -->\n<!-- [][codecov] -->\n\n<!-- [][pre-commit] -->\n<!-- [][black] -->\n\n[pypi status]: https://pypi.org/project/bw_matchbox/\n[read the docs]: https://bw_matchbox.readthedocs.io/\n[tests]: https://github.com/cauldron/bw_matchbox/actions?workflow=Tests\n[codecov]: https://app.codecov.io/gh/cauldron/bw_matchbox\n[pre-commit]: https://github.com/pre-commit/pre-commit\n[black]: https://github.com/psf/black\n\n`bw_matchbox` is a web app for matching two [Brightway](https://docs.brightway.dev/en/latest/). It allows you to do complicated matches, such as:\n\n* Link process a to processes b and c, with allocation factors\n* Link process a to a proxy for process b, changing the exchange values in b proxy to match those in process a where desired\n* Link process a to a proxy for process b, removing some exchanges from b and adding some from a\n* Link process a to a proxy for process b, expanding and inlining some exchanges from b to \"flatten\" its supply chain\n\n## Installation\n\nYou can install _bw_matchbox_ via [pip] from [PyPI]:\n\n```console\npip install bw_matchbox\n```\n\nIt's possible to install the library itself for development purposes (in the cloned project):\n\n```console\npip install -e .\n```\n\nThis library depends on:\n\n* Brightway 2.5 (`brightway25`)\n* `docopt-ng`\n* `flask` and `flask_httpauth`\n* `tomli`\n* `werkzeug`\n\n## Usage\n\nThis is a `flask` application. Flask has a debug server suitable for development, but it [should not be used for production](https://flask.palletsprojects.com/en/2.3.x/deploying/)!\n\nTo use `bw_matchbox`, you need to do the following:\n\n### Create a configuration file\n\nConfiguration is done via a `toml` file. See [`config_example.toml`](https://github.com/cauldron/bw_matchbox/blob/main/config_example.toml) for the structure of this file. Here is an example:\n\n```toml\n[users]\njane = \"deer\"\njohn = \"doe\"\n\n[roles]\neditors = [\"jane\"]\nreviewers = [\"john\"]\n\n[configs]\nmy_config = { project = \"something\", source = \"database A\", target = \"database B\", proxy = \"database C\"}\n\n[files]\noutput_dir = \"/Path/to/some/directory\"\n```\n\nThe `config.toml` file needs to provide the following:\n\n* `[users]` section: Authentication, via a set of usernames and passwords\n* `[roles]` section: The exact role labels must be used. Editors can make changes, reviewers can only comment.\n* `[configs]` section: A combination of Brightway project and the source, target and proxy databases.\n* `[files]` section: Currently only uses the `output_dir` key.\n\nThe easiest way to set this up is with:\n\n```console\nmatchbox setup\n```\n\nThis will create stub configuration and changes files in your current working directory - note that you should change the configuration and username/password in `config.toml`.\n\n### Running the development server\n\nJust run:\n\n```console\nmatchbox webapp config.toml\n```\n\n### Running in production\n\nYou will need to configure the Flask app using `configure_app`, or re-implement its functionality. Here is an example using [waitress](https://docs.pylonsproject.org/projects/waitress/en/stable/index.html):\n\n```python\nfrom bw_matchbox import matchbox_app, configure_app\nconfig_filepath = \"/path/to/config.toml\"\napp = configure_app(config_filepath, matchbox_app)\n\nfrom waitress import serve\nserve(app, port=8080)\n```\n\n### Starting the app\n\nOnce the app is running and configured locally or remotely, connect to the correct address and port. If you are running locally, this is probably either `http://localhost:5000` or `http://127.0.0.1:5000`.\n\nIn the first screen, choose the Brightway project you want to work on. This is `matchbox-example` if you ran `matchbox example_project`.\n\nOn the next screen, choose one database as the *source*, and **a different database** as the *target*. Currently you need to specify a new proxy database by typing a new database name into the *Create a new database* input box.\n\n## Contributing\n\nContributions are very welcome.\nTo learn more, see the [Contributor Guide].\n\n## License\n\nDistributed under the terms of the [MIT license][license],\n_bw_matchbox_ is free and open source software.\n\n## Issues\n\nIf you encounter any problems,\nplease [file an issue] along with a detailed description.\n\n\n<!-- github-only -->\n\n[command-line reference]: https://bw_matchbox.readthedocs.io/en/latest/usage.html\n[license]: https://github.com/cauldron/bw_matchbox/blob/main/LICENSE\n[contributor guide]: https://github.com/cauldron/bw_matchbox/blob/main/CONTRIBUTING.md\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Browser to match Brightway databases",
"version": "2.6",
"project_urls": {
"Homepage": "https://github.com/cauldron/bw_matchbox",
"source": "https://github.com/cauldron/bw_matchbox",
"tracker": "https://github.com/cauldron/bw_matchbox/issues"
},
"split_keywords": [
"\"brightway\"",
"\"development\""
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "a5d139c077bd534327f70c62953e278f187c8ba98f3984e31e313415524bd2a0",
"md5": "7b8b491d1359f19a53283e6d7d5216ec",
"sha256": "d5899e53d6a7201d292d71309745ac002f533d70908c2f3e67030590b3a9c3a0"
},
"downloads": -1,
"filename": "bw_matchbox-2.6-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7b8b491d1359f19a53283e6d7d5216ec",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 265185,
"upload_time": "2023-12-20T07:24:09",
"upload_time_iso_8601": "2023-12-20T07:24:09.890233Z",
"url": "https://files.pythonhosted.org/packages/a5/d1/39c077bd534327f70c62953e278f187c8ba98f3984e31e313415524bd2a0/bw_matchbox-2.6-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "850fcaac8d494f5fe3396cf28c1975ad109ca5244a77d0a50c360dfe4faf94a4",
"md5": "08c1f4d5b8025246faea704b02929cc4",
"sha256": "8377c826d340302c78a71896e4113d5f73e2d361e7f4ac7e04eaa4712e35985e"
},
"downloads": -1,
"filename": "bw_matchbox-2.6.tar.gz",
"has_sig": false,
"md5_digest": "08c1f4d5b8025246faea704b02929cc4",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 187796,
"upload_time": "2023-12-20T07:24:12",
"upload_time_iso_8601": "2023-12-20T07:24:12.119052Z",
"url": "https://files.pythonhosted.org/packages/85/0f/caac8d494f5fe3396cf28c1975ad109ca5244a77d0a50c360dfe4faf94a4/bw_matchbox-2.6.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-12-20 07:24:12",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "cauldron",
"github_project": "bw_matchbox",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "bw-matchbox"
}
JSON
