bfb_delivery.api package

Submodules

bfb_delivery.api.internal module

Internal functions overlay library and are typically wrapped by public functions.

This allows us to maintain a separation of API from implementation. Internal functions may come with extra options that public functions don’t have, say for power users and developers who may want to use an existing DB session or something.

bfb_delivery.api.internal.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.api.internal.combine_route_tables(input_dir, output_dir, output_filename)

Combines the driver route CSVs into a single workbook.

This is used after optimizing and exporting the routes to individual CSVs. It prepares the worksheets to be formatted with bfb_delivery.api.public.format_combined_routes().

If output_dir is specified, will create the directory if it doesn’t exist.

Note

Changes “Product Type” column name back to “Box Type”.

See Combine Driver Route Tables into a Single Workbook for more information.

Parameters:

  • input_dir (Path | str) – The directory containing the driver route CSVs.

  • output_dir (Path | str) – The directory to write the output workbook to. Empty string (default) saves to the input_dir directory.

  • output_filename (str) – The name of the output workbook. Empty string (default) will name the file ‘combined_routes_{date}.xlsx’.

Raises:

ValueError – If input_paths is empty.

Return type:

Path

Returns:

The path to the output workbook.

bfb_delivery.api.internal.create_manifests(input_dir, output_dir, output_filename, extra_notes_file)

From Circuit route CSVs, creates driver manifest workbook ready to print.

This is used after optimizing and exporting the routes to individual CSVs. Reads in driver route CSVs from input_dir and creates a formatted workbook with driver manifests ready to print, with headers, aggregate data, and color-coded box types. Each driver’s route is a separate sheet in the workbook.

The workbook is saved to output_dir with the name output_filename. Will create output_dir if it doesn’t exist.

Note

Uses the date of the front of each CSV name to set the manifest date field. I.e., each sheet should be named something like “08.08 Richard N”, and, e.g., this would set the manifest date field to “Date: 08.08”.

Just wraps bfb_delivery.api.public.combine_route_tables() and bfb_delivery.api.public.format_combined_routes(). Creates an intermediate output workbook with all routes combined, then formats it.

See Create Printable Manifests from Downloaded Optimized Routes for more information.

Parameters:

  • input_dir (Path | str) – The directory containing the driver route CSVs.

  • output_dir (Path | str) – The directory to write the formatted manifest workbook to. Empty string (default) saves to the input_dir directory.

  • output_filename (str) – The name of the output workbook.Empty string sets filename to “final_manifests_{date}.xlsx”.

  • extra_notes_file (str) – Path to the extra notes file. If empty (default), uses a constant DataFrame. See bfb_delivery.lib.constants.ExtraNotes.

Return type:

Path

Returns:

Path to the formatted manifest workbook.

bfb_delivery.api.internal.create_manifests_from_circuit(start_date, end_date, plan_ids, output_dir, output_filename, circuit_output_dir, all_hhs, verbose, extra_notes_file)

Gets optimized routes from Circuit, creates driver manifest workbook ready to print.

This is used after uploading and optimizing the routes. Reads routes CSVs from Circuit, and creates a formatted workbook with driver manifests ready to print, with headers, aggregate data, and color-coded box types. Each driver’s route is a separate sheet in the workbook.

The workbook is saved to output_dir with the name output_filename. Will create output_dir if it doesn’t exist.

Note

Uses the date of the front of each CSV name to set the manifest date field. I.e., each sheet should be named something like “08.08 Richard N”, and, e.g., this would set the manifest date field to “Date: 08.08”. But, this does not determine the search date range.

Wraps bfb_delivery.api.public.create_manifests() and adds Circuit integration. And, create_manifests just wraps bfb_delivery.api.public.combine_route_tables() and bfb_delivery.api.public.format_combined_routes(). Creates an intermediate output workbook with all routes combined, then formats it.

See Create Printable Manifests from Optimized Routes from Circuit for more information.

Parameters:

  • start_date (str) – The start date to use in the output workbook sheetnames as “YYYYMMDD”. Empty string uses the soonest Friday. Range is inclusive.

  • end_date (str) – The end date to use in the output workbook sheetnames as “YYYYMMDD”. Empty string uses the start date. Range is inclusive.

  • plan_ids (list[str]) – The list of plan IDs to filter the Circuit routes by. Overrides all_hhs. Not valid for CLI.

  • output_dir (str) – The directory to write the formatted manifest workbook to. Empty string saves to the input_dir directory.

  • output_filename (str) – The name of the output workbook. Empty string sets filename to “final_manifests_{date}.xlsx”.

  • circuit_output_dir (str) – The directory to create a subdir to save the routes to. Creates “routes_{date}” directory within the circuit_output_dir. Empty string uses output_dir. 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. Overridden by plan_ids.

  • verbose (bool) – Flag 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:

tuple[Path, Path]

Returns:

Path to the final manifest workbook.

bfb_delivery.api.internal.format_combined_routes(input_path, output_dir, output_filename, extra_notes_file)

Formats the combined routes table into driver manifests to print.

Adds headers and aggregate data. Color codes box types.

This is used after combining the driver route CSVs into a single workbook using bfb_delivery.api.public.combine_route_tables().

If output_dir is specified, will create the directory if it doesn’t exist.

Note

Uses the date of the front of each sheet name to set the manifest date field. I.e., each sheet should be named something like “05.27 Oscar W”, and, e.g., this would set the manifest date field to “Date: 05.27”.

See Format Manifests for more information.

Parameters:

  • input_path (Path | str) – The path to the combined routes table.

  • output_dir (Path | str) – The directory to write the formatted table to. Empty string (default) saves to the input path’s parent directory.

  • output_filename (str) – The name of the formatted workbook. Empty string (default) will name the file “formatted_routes_{date}.xlsx”.

  • extra_notes_file (str) – The path to the extra notes file. If empty (default), uses a constant DataFrame. See bfb_delivery.lib.constants.ExtraNotes.

Return type:

Path

Returns:

The path to the formatted table.

bfb_delivery.api.internal.split_chunked_route(input_path, output_dir, output_filename, n_books, book_one_drivers_file, date)

Split route sheet into n workbooks with sheets by driver.

Sheets by driver allows splitting routes by driver on Circuit upload. Multiple workbooks allows team to split the uploads among members, so one person doesn’t have to upload all routes. This process follows the “chunking” process in the route generation, where routes are split into smaller “chunks” by driver (i.e., each stop is labeled with a driver).

Reads a route spreadsheet at input_path. Writes n_books Excel workbooks with each sheet containing the stops for a single driver. Writes adjacent to the original workbook unless output_dir specified. If specified, will create the directory if it doesn’t exist.

Note

Renames “Box Type” column name to “Product Type”, per Circuit API.

Note

The date passed sets the date in the sheet names of the output workbooks, and that date in the sheet name is used for the manifest date field in later functions that make the manifests: bfb_delivery.api.public.format_combined_routes() and bfb_delivery.api.public.create_manifests_from_circuit() (which wraps the former).

See Split Chunked Route Sheet into Multiple Files for more information.

Parameters:

  • input_path (Path | str) – Path to the chunked route sheet that this function reads in and splits up.

  • output_dir (Path | str) – Directory to save the output workbook. Empty string saves to the input input_path directory.

  • output_filename (str) – Name of the output workbook. Empty string sets filename to “split_workbook_{date}_{i of n_books}.xlsx”.

  • n_books (int) – Number of workbooks to split into.

  • book_one_drivers_file (str) – Path to the book-one driver’s file. If empty, uses a constant list. See bfb_delivery.lib.constants.BookOneDrivers.

  • date (str) – The date to use in the output workbook sheetnames. Empty string (default) uses the soonest Friday.

Raises:

  • ValueError – If n_books is less than 1.

  • ValueError – If n_books is greater than the number of drivers in the input workbook.

Return type:

list[Path]

Returns:

Paths to the split chunked route workbooks.

bfb_delivery.api.public module

Public functions wrap internal functions which wrap library functions.

This allows separation of API from implementation. It also allows a simplified public API separate from a more complex internal API with more options for power users.

bfb_delivery.api.public.build_routes_from_chunked(input_path, output_dir='', start_date='', no_distribute=False, verbose=False, 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.api.public.combine_route_tables(input_dir, output_dir='', output_filename='')

Combines the driver route CSVs into a single workbook.

This is used after optimizing and exporting the routes to individual CSVs. It prepares the worksheets to be formatted with bfb_delivery.api.public.format_combined_routes().

If output_dir is specified, will create the directory if it doesn’t exist.

Note

Changes “Product Type” column name back to “Box Type”.

See Combine Driver Route Tables into a Single Workbook for more information.

Parameters:

  • input_dir (Path | str) – The directory containing the driver route CSVs.

  • output_dir (Path | str) – The directory to write the output workbook to. Empty string (default) saves to the input_dir directory.

  • output_filename (str) – The name of the output workbook. Empty string (default) will name the file ‘combined_routes_{date}.xlsx’.

Raises:

ValueError – If input_paths is empty.

Return type:

Path

Returns:

The path to the output workbook.

bfb_delivery.api.public.create_manifests(input_dir, output_dir='', output_filename='', extra_notes_file='')

From Circuit route CSVs, creates driver manifest workbook ready to print.

This is used after optimizing and exporting the routes to individual CSVs. Reads in driver route CSVs from input_dir and creates a formatted workbook with driver manifests ready to print, with headers, aggregate data, and color-coded box types. Each driver’s route is a separate sheet in the workbook.

The workbook is saved to output_dir with the name output_filename. Will create output_dir if it doesn’t exist.

Note

Uses the date of the front of each CSV name to set the manifest date field. I.e., each sheet should be named something like “08.08 Richard N”, and, e.g., this would set the manifest date field to “Date: 08.08”.

Just wraps bfb_delivery.api.public.combine_route_tables() and bfb_delivery.api.public.format_combined_routes(). Creates an intermediate output workbook with all routes combined, then formats it.

See Create Printable Manifests from Downloaded Optimized Routes for more information.

Parameters:

  • input_dir (Path | str) – The directory containing the driver route CSVs.

  • output_dir (Path | str) – The directory to write the formatted manifest workbook to. Empty string (default) saves to the input_dir directory.

  • output_filename (str) – The name of the output workbook.Empty string sets filename to “final_manifests_{date}.xlsx”.

  • extra_notes_file (str) – Path to the extra notes file. If empty (default), uses a constant DataFrame. See bfb_delivery.lib.constants.ExtraNotes.

Return type:

Path

Returns:

Path to the formatted manifest workbook.

bfb_delivery.api.public.create_manifests_from_circuit(start_date='', end_date='', plan_ids=[], output_dir='', output_filename='', circuit_output_dir='', all_hhs=False, verbose=False, extra_notes_file='')

Gets optimized routes from Circuit, creates driver manifest workbook ready to print.

This is used after uploading and optimizing the routes. Reads routes CSVs from Circuit, and creates a formatted workbook with driver manifests ready to print, with headers, aggregate data, and color-coded box types. Each driver’s route is a separate sheet in the workbook.

The workbook is saved to output_dir with the name output_filename. Will create output_dir if it doesn’t exist.

Note

Uses the date of the front of each CSV name to set the manifest date field. I.e., each sheet should be named something like “08.08 Richard N”, and, e.g., this would set the manifest date field to “Date: 08.08”. But, this does not determine the search date range.

Wraps bfb_delivery.api.public.create_manifests() and adds Circuit integration. And, create_manifests just wraps bfb_delivery.api.public.combine_route_tables() and bfb_delivery.api.public.format_combined_routes(). Creates an intermediate output workbook with all routes combined, then formats it.

See Create Printable Manifests from Optimized Routes from Circuit for more information.

Parameters:

  • start_date (str) – The start date to use in the output workbook sheetnames as “YYYYMMDD”. Empty string uses the soonest Friday. Range is inclusive.

  • end_date (str) – The end date to use in the output workbook sheetnames as “YYYYMMDD”. Empty string uses the start date. Range is inclusive.

  • plan_ids (list[str]) – The list of plan IDs to filter the Circuit routes by. Overrides all_hhs. Not valid for CLI.

  • output_dir (str) – The directory to write the formatted manifest workbook to. Empty string saves to the input_dir directory.

  • output_filename (str) – The name of the output workbook. Empty string sets filename to “final_manifests_{date}.xlsx”.

  • circuit_output_dir (str) – The directory to create a subdir to save the routes to. Creates “routes_{date}” directory within the circuit_output_dir. Empty string uses output_dir. 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. Overridden by plan_ids.

  • verbose (bool) – Flag 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:

tuple[Path, Path]

Returns:

Path to the final manifest workbook.

bfb_delivery.api.public.format_combined_routes(input_path, output_dir='', output_filename='', extra_notes_file='')

Formats the combined routes table into driver manifests to print.

Adds headers and aggregate data. Color codes box types.

This is used after combining the driver route CSVs into a single workbook using bfb_delivery.api.public.combine_route_tables().

If output_dir is specified, will create the directory if it doesn’t exist.

Note

Uses the date of the front of each sheet name to set the manifest date field. I.e., each sheet should be named something like “05.27 Oscar W”, and, e.g., this would set the manifest date field to “Date: 05.27”.

See Format Manifests for more information.

Parameters:

  • input_path (Path | str) – The path to the combined routes table.

  • output_dir (Path | str) – The directory to write the formatted table to. Empty string (default) saves to the input path’s parent directory.

  • output_filename (str) – The name of the formatted workbook. Empty string (default) will name the file “formatted_routes_{date}.xlsx”.

  • extra_notes_file (str) – The path to the extra notes file. If empty (default), uses a constant DataFrame. See bfb_delivery.lib.constants.ExtraNotes.

Return type:

Path

Returns:

The path to the formatted table.

bfb_delivery.api.public.split_chunked_route(input_path, output_dir='', output_filename='', n_books=4, book_one_drivers_file='', date='')

Split route sheet into n workbooks with sheets by driver.

Sheets by driver allows splitting routes by driver on Circuit upload. Multiple workbooks allows team to split the uploads among members, so one person doesn’t have to upload all routes. This process follows the “chunking” process in the route generation, where routes are split into smaller “chunks” by driver (i.e., each stop is labeled with a driver).

Reads a route spreadsheet at input_path. Writes n_books Excel workbooks with each sheet containing the stops for a single driver. Writes adjacent to the original workbook unless output_dir specified. If specified, will create the directory if it doesn’t exist.

Note

Renames “Box Type” column name to “Product Type”, per Circuit API.

Note

The date passed sets the date in the sheet names of the output workbooks, and that date in the sheet name is used for the manifest date field in later functions that make the manifests: bfb_delivery.api.public.format_combined_routes() and bfb_delivery.api.public.create_manifests_from_circuit() (which wraps the former).

See Split Chunked Route Sheet into Multiple Files for more information.

Parameters:

  • input_path (Path | str) – Path to the chunked route sheet that this function reads in and splits up.

  • output_dir (Path | str) – Directory to save the output workbook. Empty string saves to the input input_path directory.

  • output_filename (str) – Name of the output workbook. Empty string sets filename to “split_workbook_{date}_{i of n_books}.xlsx”.

  • n_books (int) – Number of workbooks to split into.

  • book_one_drivers_file (str) – Path to the book-one driver’s file. If empty, uses a constant list. See bfb_delivery.lib.constants.BookOneDrivers.

  • date (str) – The date to use in the output workbook sheetnames. Empty string (default) uses the soonest Friday.

Raises:

  • ValueError – If n_books is less than 1.

  • ValueError – If n_books is greater than the number of drivers in the input workbook.

Return type:

list[Path]

Returns:

Paths to the split chunked route workbooks.

Module contents

Public and internal APIs.