bfb_delivery.lib.dispatch package¶

Submodules¶

bfb_delivery.lib.dispatch.api_callers module¶

Classes for making API calls.

class bfb_delivery.lib.dispatch.api_callers.BaseBFBDeleteCaller¶

Bases: BaseKeyRetriever, BaseDeleteCaller

A base class for making DELETE API calls with BFB Circuit key.

class bfb_delivery.lib.dispatch.api_callers.BaseBFBGetCaller¶

Bases: BaseKeyRetriever, BaseGetCaller

A base class for making GET API calls with BFB Circuit key.

class bfb_delivery.lib.dispatch.api_callers.BaseBFBPostCaller¶

Bases: BaseKeyRetriever, BasePostCaller

A base class for making POST API calls with BFB Circuit key.

class bfb_delivery.lib.dispatch.api_callers.BaseKeyRetriever¶

Bases: object

A base class for getting the API key.

Presets the API key to be used for authentication.

_get_API_key()¶

Get the API key.

Return type:: str
Returns:: The API key.

class bfb_delivery.lib.dispatch.api_callers.BaseOptimizationCaller¶

Bases: BaseKeyRetriever, BaseCaller

A base class for checking the status of an optimization.

__init__(plan_id, plan_title)¶

Initialize the BaseOptimizationCaller object.

Parameters:

plan_id (str) – The ID of the plan. (e.g. plans/asfoghaev)
plan_title (str) – The title of the plan.

_handle_200()¶

Handle a 200 response.

Sets operation_id and whether the optimization is finished.

Raises:: RuntimeError – If the optimization was canceled, stops were skipped, or there were errors.
Return type:: None

_min_wait_seconds: float = 20¶: The minimum wait time between API calls.

_plan_id: str¶: The ID of the plan.

_plan_title: str¶: The title of the plan.

_timeout: float = 10¶: The timeout for the API call.

_wait_seconds: float = 20¶: The wait time between API calls. (Adjusted by instances, at class level.)

finished: bool¶: Whether the optimization is finished.

operation_id: str¶: The ID of the operation.

class bfb_delivery.lib.dispatch.api_callers.OptimizationChecker¶

Bases: BaseOptimizationCaller, BaseBFBGetCaller

A class for checking the status of an optimization.

__init__(plan_id, plan_title, operation_id)¶

Initialize the OptimizationChecker object.

Parameters:

plan_id (str) – The ID of the plan.
plan_title (str) – The title of the plan.
operation_id (str) – The ID of the operation.

_min_wait_seconds: float = 0.1¶: The minimum wait time between API calls.

_set_url()¶

Set the URL for the API call.

Return type:: None

_timeout: float = 10¶: The timeout for the API call.

_wait_seconds: float = 0.1¶: The wait time between API calls. (Adjusted by instances, at class level.)

class bfb_delivery.lib.dispatch.api_callers.OptimizationLauncher¶

Bases: BaseOptimizationCaller, BaseBFBPostCaller

A class for launching route optimization.

Parameters:

plan_id (str) – The ID of the plan. (e.g. plans/asfoghaev)
plan_title (str) – The title of the plan.

_set_url()¶

Set the URL for the API call with the plan_id.

Return type:: None

class bfb_delivery.lib.dispatch.api_callers.PagedResponseGetterBFB¶

Bases: BaseKeyRetriever, BasePagedResponseGetter

Class for getting paged responses.

class bfb_delivery.lib.dispatch.api_callers.PlanDeleter¶

Bases: BaseBFBDeleteCaller

Class for deleting plans.

__init__(plan_id)¶

Initialize the PlanDeleter object.

Parameters:: plan_id (str) – The ID of the plan.

_handle_204()¶

Handle a 204 response.

Sets deletion to True.

Return type:: None

_set_url()¶

Set the URL for the API call with the plan_id.

Return type:: None

deletion: bool = False¶: Whether the plan was deleted.

class bfb_delivery.lib.dispatch.api_callers.PlanDistributor¶

Bases: BaseBFBPostCaller

Class for distributing plans.

__init__(plan_id, plan_title)¶

Initialize the PlanDistributor object.

Parameters:

plan_id (str) – The ID of the plan. (e.g. plans/asfoghaev)
plan_title (str) – The title of the plan.

_handle_200()¶

Handle a 200 response.

Raises:: RuntimeError – If the plan was not distributed.
Return type:: None

_plan_id: str¶: The ID of the plan.

_plan_title: str¶: The title of the plan

_set_url()¶

Set the URL for the API call with the plan_id.

Return type:: None

distributed: bool¶

class bfb_delivery.lib.dispatch.api_callers.PlanInitializer¶

Bases: BaseBFBPostCaller

Class for initializing plans.

__init__(plan_data)¶

Initialize the PlanInitializer object.

Parameters:: plan_data (dict) – The data dictionary for the plan. To pass to requests.post json param.

_handle_200()¶

Handle a 200 response.

Sets plan_id and writable.

Return type:: None

_plan_data: dict¶: The data dictionary for the plan.

_set_url()¶

Set the URL for the API call.

Return type:: None

plan_id: str¶: The ID of the plan.

writable: bool¶: Whether the plan is writeable.

class bfb_delivery.lib.dispatch.api_callers.StopUploader¶

Bases: BaseBFBPostCaller

Class for batch uploading stops.

__init__(plan_id, plan_title, stop_array)¶

Initialize the StopUploader object.

Parameters:

plan_id (str) – The ID of the plan. (e.g. plans/asfoghaev)
plan_title (str) – The title of the plan.
stop_array (list[dict[str, dict[str, str] | list[str] | int | str]]) – The array of stops dictionaries to upload. To pass to requests.post json param.

_handle_200()¶

Handle a 200 response.

Sets stop_ids to the successful stop IDs.

Raises:

RuntimeError – If stops failed to upload.
RuntimeError – If the number of stops uploaded differs from input.

Return type:

None

_min_wait_seconds: float = 6¶: The minimum wait time between API calls.

_plan_id: str¶

_plan_title: str¶

_set_url()¶

Set the URL for the API call with plan_id.

Return type:: None

_wait_seconds: float = 6¶: The wait time between API calls. (Adjusted by instances, at class level.)

stop_ids: list[str]¶

bfb_delivery.lib.dispatch.read_circuit module¶

Read from Circuit.

bfb_delivery.lib.dispatch.read_circuit._clean_title(title_series, warn)¶

Clean the title column.

Return type:: Series

bfb_delivery.lib.dispatch.read_circuit._count_allhhs_dropped(all_hhs, plan_count, plan_mask)¶

Return type:: None

bfb_delivery.lib.dispatch.read_circuit._count_plan_ids_dropped(plan_count, plan_mask)¶

Return type:: None

bfb_delivery.lib.dispatch.read_circuit._get_plan_responses(url)¶

Return type:: list[dict[str, Any]]

bfb_delivery.lib.dispatch.read_circuit._get_raw_plans(start_date, end_date, verbose)¶

Call Circuit API to get the plans for the given date.

Return type:: list[dict[str, Any]]

bfb_delivery.lib.dispatch.read_circuit._get_raw_stops(plan_ids, verbose)¶

Get the raw stops list from Circuit.

Return type:: list[dict[str, Any]]

bfb_delivery.lib.dispatch.read_circuit._get_raw_stops_list(plan_ids, verbose)¶

Return type:: list[Any]

bfb_delivery.lib.dispatch.read_circuit._get_stops_responses(url)¶

Return type:: list[dict[str, Any]]

bfb_delivery.lib.dispatch.read_circuit._getcwd()¶

Wrapping to allow restricted mocking.

Return type:: str

bfb_delivery.lib.dispatch.read_circuit._make_plans_df(plans_list, all_hhs, plan_ids=None, verbose=False)¶

Make the plans DataFrame from the plans.

Return type:: DataFrame[CircuitPlansOut]

bfb_delivery.lib.dispatch.read_circuit._pare_routes_df(routes_df, verbose)¶

Return type:: DataFrame

bfb_delivery.lib.dispatch.read_circuit._set_routes_df_values(routes_df)¶

Return type:: DataFrame

bfb_delivery.lib.dispatch.read_circuit._split_multi_route_drivers(routes_df)¶

If a driver sheet name has multiple routes, split them into separate sheet names.

Return type:: None

bfb_delivery.lib.dispatch.read_circuit._warn_and_impute(routes_df)¶

Warn and impute missing values in the routes DataFrame.

Return type:: None

bfb_delivery.lib.dispatch.read_circuit.get_route_files(start_date, end_date, plan_ids, output_dir, all_hhs=False, verbose=False)¶

Get the route files for the given date.

Parameters:

start_date (str) – The start date to get the routes for, as “YYYYMMDD”. Empty string uses the soonest Friday.
end_date (str) – The end date to get the routes for, as “YYYYMMDD”. Empty string uses the start date.
plan_ids (list[str]) – The plan IDs to get the routes for. Overrides all_hhs.
output_dir (str) – The directory to create a subdir to save the routes to. Creates “routes_{date}” directory within the output_dir. Empty string uses the current working directory. If the directory does not exist, it is created. If it exists, it is overwritten.
all_hhs (bool) – Flag to get only the “All HHs” route. False gets all routes except “All HHs”. True gets only the “All HHs” route. Overriden by plan_ids.
verbose (bool) – Flag to print verbose output.

Return type:

str

Returns:

The path to the route files.

Raises:

ValueError – If no plans are found for the given date range.
ValueError – If no plans with routes are found.
ValueError – If no stops are found for the given plans.
ValueError – If no routed stops are found for the given plans.

bfb_delivery.lib.dispatch.utils module¶

Utility functions for the dispatch module.

bfb_delivery.lib.dispatch.utils.get_circuit_key()¶

Get the Circuit API key.

Return type:: str

bfb_delivery.lib.dispatch.write_to_circuit module¶

Write routes to Circuit.

bfb_delivery.lib.dispatch.write_to_circuit._build_stop_array(route_stops, driver_id)¶

Build a stop array for a route.

Return type:: list[dict[str, Any]]

bfb_delivery.lib.dispatch.write_to_circuit._create_stops_df(split_chunked_workbook_fp, stops_df_path)¶

Return type:: DataFrame

bfb_delivery.lib.dispatch.write_to_circuit._parse_addresses(stops_df)¶

Parse addresses for each route.

Return type:: DataFrame

bfb_delivery.lib.dispatch.write_to_circuit._print_report(plan_df, no_distribute)¶

Print a report of upload results.

Return type:: None

bfb_delivery.lib.dispatch.write_to_circuit.build_routes_from_chunked(input_path, output_dir, start_date, no_distribute, verbose, extra_notes_file)¶

Build and disbribute routes from chunked routes.

From a chunked route spreadsheet, builds, optimizes, and distributes routes to drivers. Produces a final manifest spreadsheet.

Prompts interactive user input to confirm driver assignments.

See Build, Optimize, and Distribute Circuit Routes from Chunked Routes Sheet for more information.

Parameters:

input_path (str) – Path to the chunked route spreadsheet.
output_dir (str) – Path to the output directory. Empty defaults to a new directory in the present working directory, named “deliveries_{date}”.
start_date (str) – The date to start the routes, as “YYYY-MM-DD”. Empty string defaults to the soonest Friday.
no_distribute (bool) – To skip distributing the routes to drivers after optimizing.
verbose (bool) – Whether to print verbose output.
extra_notes_file (str) – Path to the extra notes file. If empty, uses a constant DataFrame. See bfb_delivery.lib.constants.ExtraNotes.

Return type:

Path

Returns:

The path to the final manifest spreadsheet.

bfb_delivery.lib.dispatch.write_to_circuit.delete_plan(plan_id)¶

Delete a plan from Circuit.

Parameters:: plan_id (str) – The plan ID to be deleted.
Return type:: bool
Returns:: Whether the plan was deleted. (Should always be True if no errors.)

bfb_delivery.lib.dispatch.write_to_circuit.delete_plans(plan_ids, plan_df_fp)¶

Delete plans from Circuit.

Parameters:

plan_ids (list[str]) – The plan IDs to delete.
plan_df_fp (str) – The file path to a dataframe with plan IDs to be deleted in column ‘plan_id’.

Return type:

list[str]

Returns:

The plan IDs that were (to be) deleted.

Raises:

ValueError – If both plan_ids and plan_df_fp are provided.
ValueError – If neither plan_ids nor plan_df_fp are provided.
RuntimeError – If there are errors deleting plans.

Module contents¶

Dispatch module for the BFB delivery system.