Create Printable Manifests from Optimized Routes from Circuit¶
After you have optimized each driver’s route in Circuit, you will need to combine the optimized routes back into a single workbook of driver manifests ready to print, with headers, aggregate data, and color-coded box types. You can do this with the create_manifests_from_circuit tool.
This tool replaces the manual task of downloading the optimized routes, copying each route into a single workbook, running an Excel macro, and finishing up with some manual steps. Instead, create_manifests_from_circuit will download and combine all the optimized routes into a single workbook, with each driver’s route on a separate sheet, and format the sheets into manifests ready to print.
Note
Uses the date of the front of each route’s title to set the manifest date field. I.e., each route should be titled something like “07.17 Walt D”, and, e.g., this would set the manifest date field to “Date: 07.17”.
Python API documentation at bfb_delivery.api.public.create_manifests_from_circuit().
CLI documentation at CLI.
Usage¶
You call create_manifests_from_circuit with (optionally) the start date of the routes, along with any other optional arguments, and it will create a single workbook file with all the optimized routes formatted and ready to print. The tool then returns the filepath to that file.
Note
The filepaths to some intermediate files will print to the console as well, before finally printing the filepath to the final workbook. In addition to the final manifest, there will route CSVs in a directory and an unformatted workbook of all the routes.
Note
This will change the “Product Type” column name, per Circuit API, back to “Box Type” per food bank staff preferences.
In Python:
from bfb_delivery import create_manifests_from_circuit
create_manifests_from_circuit(start_date="1903-12-17")
With CLI:
create_manifests_from_circuit --start_date 1919-06-14
The function will return the filepath to the final manifest. If you’re using the CLI, the filepath will print to the console.
Note
This takes about a minute to run as it downloads the routes from Circuit.
Note
You don’t need to pass in start_date. If you don’t pass it in, the tool will assume the soonest Friday.
Optional arguments¶
You can use optional arguments to specify a few things about the manifest workbook. Use –help to see all the optional arguments in the CLI.
create_manifests_from_circuit --help
Start date¶
Use the optional argument start_date to specify the beginning of the date range to search Circuit for routes. The default if not passed in is the soonest Friday.
from bfb_delivery import create_manifests_from_circuit
create_manifests_from_circuit(start_date="1947-10-14")
With CLI:
create_manifests_from_circuit --start_date 1957-10-04
End date¶
Use the optional argument end_date to specify the end of the date range to search Circuit for routes. The default is the start date.
from bfb_delivery import create_manifests_from_circuit
create_manifests_from_circuit(end_date="1961-04-12")
With CLI:
create_manifests_from_circuit --end_date 1969-07-20
Output directory¶
Use the optional argument output_dir to specify the directory to save the workbook file in.
In Python:
create_manifests_from_circuit(output_dir="path/to/output_dir/")
With CLI:
create_manifests_from_circuit --output_dir path/to/output_dir/
Output filename¶
Choose the filename with output_name. The default filename will be final_manifests_{today's date}.xlsx (e.g., final_manifests_19991231.xlsx). But, you can pass a preferred name instead.
In Python:
create_manifests_from_circuit(output_name="all_routes.xlsx")
With CLI:
create_manifests_from_circuit --output_name all_routes.xlsx
Note
You can use both output_dir and output_name together to specify the directory and filename of the output workbook.
Circuit output directory¶
Use the optional argument circuit_output_dir to specify the directory in which to save the route CSVs downloaded from Circuit.
In Python:
create_manifests_from_circuit(circuit_output_dir="path/to/circuit_output_dir/")
With CLI:
create_manifests_from_circuit --circuit_output_dir path/to/circuit_output_dir/
All HHs¶
If you want to get the “All HHs” route that was optimized as a single route before chunking into driver routes, use the optional argument all_hhs.
In Python:
create_manifests_from_circuit(all_hhs=True)
With CLI:
create_manifests_from_circuit --all_hhs
Note
If you’re using this, you’re not likely using it to create a final manifest, but rather a plain spreadsheet to start chunking into separate routes. So, you’ll want look in the console for the filepath to the combined workbook, not the final manifest.
Verbose output¶
Use the optional argument verbose to print more information to the console.
In Python:
create_manifests_from_circuit(verbose=True)
With CLI:
create_manifests_from_circuit --verbose
Supplying extra notes¶
Use the optional argument extra_notes_file to specify a CSV file with extra notes to include in the manifest. The CSV file should have two columns: tag and note. The tag is the text (usually asterisked) that appears in the standard notes field for a delivery. The note is then added to the bottom of the manifest with the tag. For example:
tag,note
Cedarwood Apartments special instructions *,Please call the recipient when you arrive.
This file will put the note “Please call the recipient when you arrive.” at the bottom of the manifest (once) if any stops have a note that contains the text “Cedarwood Apartments special instructions *”.
If you don’t provide extra_notes_file provide, the tool will use the constant notes in the codebase: bfb_delivery.lib.constants.ExtraNotes (currently empty).
In Python:
create_manifests_from_circuit(extra_notes_file="path/to/extra_notes.csv")
With CLI:
create_manifests_from_circuit --extra_notes_file path/to/extra_notes.csv
Note on tools this tool wraps¶
create_manifests_from_circuit wraps another tool, create_manifests, so you don’t have to download and move files around. create_manifests in turn wraps two other tools, combine_route_tables and format_combined_routes into one tool. You can still use any of those tools if you wish, but you can instead just use create_manifests_from_circuit.
graph TD;
A[**create_manifests_from_circuit**] --> B[Gets routes from Circuit]
A --> C[**create_manifests**]
C --> D[**combine_route_tables**]
C --> E[**format_combined_routes**]
Subtools wrapped and alternatively available for use¶
For instance, say you’ve found a bug when using create_manifests_from_circuit. You could try downloading the routes manually and running create_manifests, or running combine_route_tables and passing its output to format_combined_routes. For whichever of those steps fails you can revert to using your old method, but you can still ostensibly use the tool for the other piece that didn’t fail. For example, say combine_route_tables ran fine, but format_combined_routes threw an error, so you reverted to using the old Excel macro and manually formatting. See Create Printable Manifests from Downloaded Optimized Routes, Combine Driver Route Tables into a Single Workbook and Format Manifests.
Most likely you’ll find that the tool works fine unless the underlying data schemata have changed, but it’s good to know you have options to explore instead of doing it all manually again.
See Also¶
The Delivery-Planning Workflow
Create Printable Manifests from Downloaded Optimized Routes