| Name | bfb-delivery JSON |
| Version |
0.2.7
JSON |
| download |
| home_page | None |
| Summary | Tools to help plan deliveries for Bellingham Food Bank. |
| upload_time | 2024-12-27 03:16:59 |
| maintainer | None |
| docs_url | None |
| author | Kaleb Coberly |
| requires_python | >=3.11 |
| license | None |
| keywords |
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Bellingham Food Bank delivery planning toolkit
## Summary
This doesn't do much yet. It is made from the `reference_package` template repo: https://github.com/crickets-and-comb/reference_package. See the docs: https://crickets-and-comb.github.io/bfb_delivery/.
The plan is to use this package for some of the tasks food bank staff do manually to plan the delivery routes.
They currently use Circuit (https://getcircuit.com), but there are some tedious tasks to prepare the data for Circuit and then to process the data after using Circuit. They currently upload all the stops they need to Circuit to produce a single huge route, then they manually chunk up the route by driver according to how many boxes a driver can carry and what is a sensible set of stops, and finally they upload those smaller routes to Circuit again to optimize them. They spend several hours each week on the manual pieces of this, the chunking alone taking about four hours.
## What it does so far
1. Splits a spreadsheet of delivery stops labeled by driver into n workbooks (1 per staff member working on the route generation), one workbook sheet per driver. This allows staff to split the task of submitting unique driver routes to Circuit. The tool for this is called `split_chunked_route`. See below and/or docs for usage.
2. Combines route CSVs into a single workbook with a sheet for each route. The tool for this is called `combine_route_tables`. See docs for usage.
## Dev plan
Without replacing Circuit, there are some processes that can be further automated:
- Chunking by driver: This may be the most challenging piece, I'm not confident I can solve this well enough to justify using my solution. So, I will save it for after I've cleared some of the low-hanging fruit. My first plan of attack is to try using k-nearest neighbors.
- Formatting those sheets into the final sheets used for records and printing for drivers. They currently have a spreadsheet macro do most of this, but there are some pieces they still need to do manually. These solutions could probably be implemented in the spreadsheet, and that may be the best solution if they want to keep the macro. But, it might be simpler to replace the macro with formatting at the end of the ETL above.
- Uploading and exporting can be done via the Circuit API, which would enable the above steps to be wrapped into a single ETL pipeline.
The plan of attack is to start with the low-hanging fruit of data formatting before moving onto the bigger problem of chunking. Integrating with the Circuit API may come before or after the chunking solution, depending on how complicated each proves.
## Structure
```bash
src/bfb_delivery/api Public and internal API.
src/bfb_delivery/cli Command-line-interface.
src/bfb_delivery/lib Implementation.
tests/e2e End-to-end tests.
test/integration Integration tests.
tests/unit Unit tests.
```
## Dependencies
* Python 3.11
* [make](https://www.gnu.org/software/make/)
## Installation
Run `pip install bfb_delivery`. See https://pypi.org/project/bfb-delivery/.
## Usage Examples
See docs for full usage.
### Public API
`bfb_delivery` is a library from which you can import functions. Import the public `split_chunked_route` function like this:
```python
from bfb_delivery import split_chunked_route
# These are okay too:
# from bfb_delivery.api import split_chunked_route
# from bfb_delivery.api.public import split_chunked_route
```
Or, if you're a power user and want any extra options that may exist, you may want to import the internal version like this:
```python
from bfb_delivery.api.internal import split_chunked_route
```
Unless you're developing, avoid importing directly from library:
```python
# Don't do this:
from bfb_delivery.lib.formatting.sheet_shaping import split_chunked_route
```
### CLI
Try the CLI with this package installed:
$ split_chunked_route --input_path "some/path_to/raw_chunked_sheet.xlsx"
See other options in the help menu:
$ split_chunked_route --help
CLI tools (see docs for more information):
- combine_route_tables
- split_chunked_route
## Dev installation
You'll want this package's site-package files to be the source files in this repo so you can test your changes without having to reinstall. We've got some tools for that.
First build and activate the env before installing this package:
$ make build-env
$ conda activate bfb_delivery_py3.12
(Note, you will need Python activated, e.g. via conda base env, for `build-env` to work, since it uses Python to grab `PACKAGE_NAME` in the Makefile. You could alternatively just hardcode the name.)
Then, install this package and its dev dependencies:
$ make install INSTALL_EXTRAS=[dev]
This installs all the dependencies in your conda env site-packages, but the files for this package's installation are now your source files in this repo.
## Dev workflow
You can list all the make tools you might want to use:
$ make list-targets
Go check them out in `Makefile`.
### QC and testing
Before pushing commits, you'll usually want to rebuild the env and run all the QC and testing:
$ make clean full
When making smaller commits, you might just want to run some of the smaller commands:
$ make clean format full-qc full-test
### CI test run
Before opening a PR or pushing to it, you'll want to run locally the same CI pipeline that GitHub will run (`.github/workflows/QC-and-build.yml`). This runs on multiple images, so you'll need to install Docker and have it running on your machine: https://www.docker.com/
Once that's installed and running, you can use `act`. You'll need to install that as well. I develop on a Mac, so I used `homebrew` to install it (which you'll also need to install: https://brew.sh/):
$ brew install act
Then, run it from the repo directory:
$ make ci-run
That will run `.github/workflows/QC-and-build.yml` and every other action tagged to the pull_request event. Also, since `act` doesn't work with Mac and Windows architecture, it skips/fails them, but it is a good test of the Linux build.
Raw data
{
"_id": null,
"home_page": null,
"name": "bfb-delivery",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": "kaleb.coberly@gmail.com",
"keywords": null,
"author": "Kaleb Coberly",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/3e/e2/2f065a109337021941098678abadd894ec52f80e9f29f608c6e38025bbf8/bfb_delivery-0.2.7.tar.gz",
"platform": null,
"description": "# Bellingham Food Bank delivery planning toolkit\n\n## Summary\n\nThis doesn't do much yet. It is made from the `reference_package` template repo: https://github.com/crickets-and-comb/reference_package. See the docs: https://crickets-and-comb.github.io/bfb_delivery/.\n\nThe plan is to use this package for some of the tasks food bank staff do manually to plan the delivery routes.\n\nThey currently use Circuit (https://getcircuit.com), but there are some tedious tasks to prepare the data for Circuit and then to process the data after using Circuit. They currently upload all the stops they need to Circuit to produce a single huge route, then they manually chunk up the route by driver according to how many boxes a driver can carry and what is a sensible set of stops, and finally they upload those smaller routes to Circuit again to optimize them. They spend several hours each week on the manual pieces of this, the chunking alone taking about four hours.\n\n## What it does so far\n\n1. Splits a spreadsheet of delivery stops labeled by driver into n workbooks (1 per staff member working on the route generation), one workbook sheet per driver. This allows staff to split the task of submitting unique driver routes to Circuit. The tool for this is called `split_chunked_route`. See below and/or docs for usage.\n\n2. Combines route CSVs into a single workbook with a sheet for each route. The tool for this is called `combine_route_tables`. See docs for usage.\n\n## Dev plan\n\nWithout replacing Circuit, there are some processes that can be further automated:\n- Chunking by driver: This may be the most challenging piece, I'm not confident I can solve this well enough to justify using my solution. So, I will save it for after I've cleared some of the low-hanging fruit. My first plan of attack is to try using k-nearest neighbors.\n- Formatting those sheets into the final sheets used for records and printing for drivers. They currently have a spreadsheet macro do most of this, but there are some pieces they still need to do manually. These solutions could probably be implemented in the spreadsheet, and that may be the best solution if they want to keep the macro. But, it might be simpler to replace the macro with formatting at the end of the ETL above.\n- Uploading and exporting can be done via the Circuit API, which would enable the above steps to be wrapped into a single ETL pipeline.\n\nThe plan of attack is to start with the low-hanging fruit of data formatting before moving onto the bigger problem of chunking. Integrating with the Circuit API may come before or after the chunking solution, depending on how complicated each proves.\n\n## Structure\n\n```bash\n src/bfb_delivery/api Public and internal API.\n src/bfb_delivery/cli Command-line-interface.\n src/bfb_delivery/lib Implementation.\n tests/e2e End-to-end tests.\n test/integration Integration tests.\n tests/unit Unit tests.\n```\n\n## Dependencies\n\n* Python 3.11\n* [make](https://www.gnu.org/software/make/)\n\n## Installation\n\nRun `pip install bfb_delivery`. See https://pypi.org/project/bfb-delivery/.\n\n## Usage Examples\n\nSee docs for full usage.\n\n### Public API\n\n`bfb_delivery` is a library from which you can import functions. Import the public `split_chunked_route` function like this:\n\n```python\n from bfb_delivery import split_chunked_route\n # These are okay too:\n # from bfb_delivery.api import split_chunked_route\n # from bfb_delivery.api.public import split_chunked_route\n```\n\nOr, if you're a power user and want any extra options that may exist, you may want to import the internal version like this:\n\n```python\n from bfb_delivery.api.internal import split_chunked_route\n```\n\nUnless you're developing, avoid importing directly from library:\n\n```python\n # Don't do this:\n from bfb_delivery.lib.formatting.sheet_shaping import split_chunked_route\n```\n\n### CLI\n\nTry the CLI with this package installed:\n\n $ split_chunked_route --input_path \"some/path_to/raw_chunked_sheet.xlsx\"\n\nSee other options in the help menu:\n\n $ split_chunked_route --help\n\nCLI tools (see docs for more information):\n- combine_route_tables\n- split_chunked_route\n\n\n\n## Dev installation\n\nYou'll want this package's site-package files to be the source files in this repo so you can test your changes without having to reinstall. We've got some tools for that.\n\nFirst build and activate the env before installing this package:\n\n $ make build-env\n $ conda activate bfb_delivery_py3.12\n\n(Note, you will need Python activated, e.g. via conda base env, for `build-env` to work, since it uses Python to grab `PACKAGE_NAME` in the Makefile. You could alternatively just hardcode the name.)\n\nThen, install this package and its dev dependencies:\n\n $ make install INSTALL_EXTRAS=[dev]\n\nThis installs all the dependencies in your conda env site-packages, but the files for this package's installation are now your source files in this repo.\n\n## Dev workflow\n\nYou can list all the make tools you might want to use:\n\n $ make list-targets\n\nGo check them out in `Makefile`.\n\n### QC and testing\n\nBefore pushing commits, you'll usually want to rebuild the env and run all the QC and testing:\n\n $ make clean full\n\nWhen making smaller commits, you might just want to run some of the smaller commands:\n\n $ make clean format full-qc full-test\n\n### CI test run\n\nBefore opening a PR or pushing to it, you'll want to run locally the same CI pipeline that GitHub will run (`.github/workflows/QC-and-build.yml`). This runs on multiple images, so you'll need to install Docker and have it running on your machine: https://www.docker.com/\n\nOnce that's installed and running, you can use `act`. You'll need to install that as well. I develop on a Mac, so I used `homebrew` to install it (which you'll also need to install: https://brew.sh/):\n\n $ brew install act\n\nThen, run it from the repo directory:\n\n $ make ci-run\n\nThat will run `.github/workflows/QC-and-build.yml` and every other action tagged to the pull_request event. Also, since `act` doesn't work with Mac and Windows architecture, it skips/fails them, but it is a good test of the Linux build.\n",
"bugtrack_url": null,
"license": null,
"summary": "Tools to help plan deliveries for Bellingham Food Bank.",
"version": "0.2.7",
"project_urls": null,
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "dcdd07477f473ce43a7739a8cf4395e6a1f60f742bbbdb64e3e2fa2c062ef1c9",
"md5": "1f3a2724539dad3d49f7f4113e695ea6",
"sha256": "29597e03fb2315fb266c992e1610d4684dfb5fa0da858d33d0bd8d955decb7d6"
},
"downloads": -1,
"filename": "bfb_delivery-0.2.7-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1f3a2724539dad3d49f7f4113e695ea6",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 11642,
"upload_time": "2024-12-27T03:16:57",
"upload_time_iso_8601": "2024-12-27T03:16:57.491732Z",
"url": "https://files.pythonhosted.org/packages/dc/dd/07477f473ce43a7739a8cf4395e6a1f60f742bbbdb64e3e2fa2c062ef1c9/bfb_delivery-0.2.7-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "3ee22f065a109337021941098678abadd894ec52f80e9f29f608c6e38025bbf8",
"md5": "468eeba5c2afeaf230015636301a90f0",
"sha256": "f4edbaa8f1a1f5690d1fb2ab3d121fcccb1a7494f424c6740192e7c1e5bc8933"
},
"downloads": -1,
"filename": "bfb_delivery-0.2.7.tar.gz",
"has_sig": false,
"md5_digest": "468eeba5c2afeaf230015636301a90f0",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 11899,
"upload_time": "2024-12-27T03:16:59",
"upload_time_iso_8601": "2024-12-27T03:16:59.718432Z",
"url": "https://files.pythonhosted.org/packages/3e/e2/2f065a109337021941098678abadd894ec52f80e9f29f608c6e38025bbf8/bfb_delivery-0.2.7.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-27 03:16:59",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "bfb-delivery"
}
