API

KiABOM utilises KiCost to retrieve part data from suppliers, and to use the cache functionalities it provides. The KiCad netlist reader module is used to read the schematic, and the KiCost data is matched to what was read so that it is outputed in the correct order. To retrieve more data, the KiCost query functions are overwritten but made sure to achieve the same functionality for compatibility.

Summary

Functions

check_args(args)

Check the input arguments are valid.

check_empty_dnp(component)

Fixes issue of outputting an empty DNP component list, which is what happens when

digikey_new_query_part_info(parts, ...)

Used to override the api_digikey._query_part_info function to return additional part details like the manufacturer.

download_datasheets(grouped[, ...])

Download the datasheets from the 'Datasheets' symbol field

fill_primary_list_gaps_with_secondary(...)

Fills the gaps in the primary list with the data from the secondary list.

get_columns(columns, preset)

Get the specified columns for use during BOM generation.

get_equ(group_fields, group_preset, ...)

Return the selected equivalence function to be used in grouping

get_footprint_name(text)

Get the footprint name from the Lib:Name string in the footprint symbol field.

get_html_td_string(string)

Get a string as a table data cell HTML element.

get_return_empty(no_kicost, primary_only)

Get if any parts need to not be searched and returned empty lists

get_total_price_sum(parts_prices, ...)

Get the total price sum to add to the end of the BOM table

has_internet([test_address, timeout])

Check if there is a valid internet connection.

init_kicost()

Initialise KiCost by initialising the logger and the APIs.

main(argv)

Main function executed when __name__ is "__main__".

match_netlist_refs_with_api_refs(lst1, lst2)

Matches the group number and location of a reference in lst1 to what group and location it is in lst2, and uses counters to store the indexes.

mouser_new_query_part_info(parts, ...)

Used to override the api_digikey._query_part_info function to return additional part details like the manufacturer.

open_output_file(output_file)

Open the file to be used for outputing the BOM data.

output_general_info_csv(out, net, board_quantity)

output_general_info_html(html, net, ...)

Output some general info afte the HTML BOM table.

print_title_screen()

Print the title splash.

refs_sort(ref)

Used as a sort key in get_refs_from_kicost().

remove_ignore_mpn_parts(grouped, ignore_mpns)

set_format_from_output_file_extension(...)

Automatically set the output format based on the output file extension

set_html_table(html_text, board_quantity, ...)

Set the table in the HTML string.

write_parts_to_csv(out, board_quantity, ...)

Write grouped parts into the opened CSV file

write_to_file(f, output_format, ...)

Write to the corresponding file the collated data.

writerow(acsvwriter, columns)

Override csv.writer's writerow() to support encoding conversion (initial encoding is utf8)

Classes

BaseNet(input_xml, excludeBOM, excludeBoard)

Base Net class where Net and NetDNP inherit their shared members

BaseParts(supplier, net_obj, return_empty, ...)

Base class for the Parts and PartsDNP classes containing KiCost part details as lists.

BasePartsFileData(primary_parts_obj, ...)

Class containing the file data that is common between DNP and non-DNP parts.

Net(input_xml, excludeBOM, excludeBoard)

Contains data read by the netlist reader.

NetDNP(input_xml, excludeBOM, excludeBoard)

Contains data read by the netlist reader for DNP components.

Parts(supplier, net_obj, return_empty, ...)

Contains non-DNP parts data retrieved by KiCost for a specific supplier.

PartsDNP(supplier, net_obj, return_empty, ...)

Contains DNP parts data retrieved by KiCost for a specific supplier

PartsFileData(primary_parts_obj, ...)

Contains data of the parts as simple lists for outputting.

PartsFileDataDNP(primary_parts_obj, ...)

Contains DNP CSV data of the DNP parts

Definitions

Definitions for the above summary tables.

Functions

kiabom.check_args(args: Namespace)

Check the input arguments are valid.

Parameters:

args – Input arguments.

kiabom.check_empty_dnp(component: comp) → bool
Fixes issue of outputting an empty DNP component list, which is what happens when

no DNP components exist in the XML. The empty DNP value is set by extract_dnp().

Parameters:

component – Component to check.

Returns:

True or False.

kiabom.digikey_new_query_part_info(parts: OrderedDict, distributors: list[str], currency: list[str])

Used to override the api_digikey._query_part_info function to return additional part details like the manufacturer.

Parameters:

  • parts – Parts read by KiCost.

  • distributors – The chosen distributor which in this case will be digikey.

  • currency – Chosen currency of returned prices.

kiabom.download_datasheets(grouped: list[list[comp]], downloads_folder: str = 'datasheets', timeout: int = 2)

Download the datasheets from the ‘Datasheets’ symbol field

Parameters:

  • grouped – A list containing lists of grouped parts

  • downloads_folder – Downloads folder name

  • timeout – Time in seconds where the internet connection will time out.

kiabom.fill_primary_list_gaps_with_secondary(primary_list: list[str], secondary_list: list[str]) → list[str]

Fills the gaps in the primary list with the data from the secondary list.

Parameters:

  • primary_list – A list containining blank or filled string data.

  • secondary_list – A list containining blank or filled string data.

Returns:

Primary list with its blanks filled by the secondary list.

kiabom.get_columns(columns: str, preset: str) → list[str]

Get the specified columns for use during BOM generation.

Parameters:

  • columns – Comma separated string of the columns names.

  • preset – Specified column list preset.

Returns:

A column string list.

kiabom.get_equ(group_fields: str, group_preset: str, append_groups: str)

Return the selected equivalence function to be used in grouping

Parameters:

  • group_fields – String of comma separated group values.

  • group_preset – Specified group preset.

  • append_groups – String of comma separated values to append to a preset.

Returns:

Equivalence (__equ__) function.

Return type:

Function returning True or False.

kiabom.get_footprint_name(text: str) → str

Get the footprint name from the Lib:Name string in the footprint symbol field.

Parameters:

text – Footprint field string.

Returns:

Footprint name or blank.

kiabom.get_html_td_string(string: str) → str

Get a string as a table data cell HTML element.

Parameters:

string – Text to be placed between the <td> and </td>.

Returns:

String encloded by <td> and </td>.

kiabom.get_return_empty(no_kicost: bool, primary_only: bool) → tuple

Get if any parts need to not be searched and returned empty lists

Parameters:

  • no_kicost – Flag if no KiCost should be used

  • primary_only – Flag if only the primary supplier should be used

Returns:

A tuple of boolean values. Used to decide if the suppliers objects should be empty lists.

kiabom.get_total_price_sum(parts_prices: list[str], parts_prices_dnp: list[str], board_quantity: int) → float

Get the total price sum to add to the end of the BOM table

Parameters:

  • parts_prices – List of part prices.

  • parts_price_dnp – List of DNP part prices.

  • board_quantity – Specified board quantity.

Returns:

Total price sum.

kiabom.has_internet(test_address: str = '8.8.8.8', timeout: int = 5) → bool

Check if there is a valid internet connection.

Parameters:

  • test_address – Address used to test for internet connection.

  • timeout – Time to wait until a valid internet connection is established.

Returns:

True or False on whether there is an internet connection.

kiabom.init_kicost() → bool

Initialise KiCost by initialising the logger and the APIs.

Returns:

True or Fasle (Success or Failure).

kiabom.main(argv: list[str])

Main function executed when __name__ is “__main__”.

Parameters:

argv – Argument vector containing command line options.

kiabom.match_netlist_refs_with_api_refs(lst1: list[list[str]], lst2: list[list[str]]) → list[list[str]]

Matches the group number and location of a reference in lst1 to what group and location it is in lst2, and uses counters to store the indexes. In this software’s case, lst1 = Net list reader reference groups and lst2 = API reference groups.

This function used to be used for extracting from the KiCost result only the components present in the net list. Now it is used to sort the KiCost result exactly how the net list reader does it so that the results can simply be indexed.

Format of returned list is [lst1_group_index, lst1_ref_index, lst2_group_index, lst2_ref_index].

Parameters:

  • lst1 – List with nested lists of strings.

  • lst2 – List with nested lists of strings.

Returns:

List with nested lists of indexes where lst1 nested items match lst2 nested items. Goupred based on the location in lst1.

kiabom.mouser_new_query_part_info(parts: OrderedDict, distributors: list[str], currency: list[str])

Used to override the api_digikey._query_part_info function to return additional part details like the manufacturer.

Parameters:

  • parts – Parts read by KiCost.

  • distributors – The chosen distributor which in this case will be digikey.

  • currency – Chosen currency of returned prices.

kiabom.open_output_file(output_file: str) → TextIOWrapper

Open the file to be used for outputing the BOM data.

Parameters:

output_file – Output file name.

Returns:

A file object.

kiabom.output_general_info_csv(out, net: netlist, board_quantity: int)
Parameters:

  • out (csv.writer.) – A csv.writer object created with csv.writer().

  • net – The netlist object created by opening the XML with kicad_netlist_reader.

  • board_quantity – Board quantity.

kiabom.output_general_info_html(html: str, net: netlist, board_quantity: int) → str

Output some general info afte the HTML BOM table.

Parameters:

  • html – HTML string.

  • net – Netlist object opened using kicad_netlist_reader.

  • board_quantity – Board quantity.

Returns:

HTML string.

kiabom.print_title_screen()

Print the title splash.

kiabom.refs_sort(ref: str) → list[int]

Used as a sort key in get_refs_from_kicost().

For example, KiCost sorts a reference like so [‘R2’, ‘R9’, ‘R13’, ‘R14’, ‘R10’] whereas kicad_netlist_reader sorts it like so [‘R2’, ‘R9’, ‘R10’, ‘R13’, ‘R14’]. Therefore for optimum matching between the two outputs, they need to be sorted the same way.

Parameters:

ref – Reference designator string.

Returns:

A list

kiabom.remove_ignore_mpn_parts(grouped: list[list[comp]], ignore_mpns: list[str]) → list[list[comp]]
kiabom.set_format_from_output_file_extension(output_file: str) → str

Automatically set the output format based on the output file extension

Parameters:

output_file – Output file name.

Returns:

Output file format.

kiabom.set_html_table(html_text: str, board_quantity: int, columns: list[str], grouped: list[list[comp]], output_data: PartsFileData | PartsFileDataDNP) → str

Set the table in the HTML string.

Parameters:

  • html_text – HTML string.

  • board_quantity – Board quantity.

  • columns – Columns list for what data to output.

  • grouped – List of lists of components from the kicad_netlist_reader.

  • output_data – Parts data that will be used to populate the table.

Returns:

HTML table string containing all the parts data.

kiabom.write_parts_to_csv(out, board_quantity: int, columns: list[str], grouped: list[list[comp]], output_data: PartsFileData | PartsFileDataDNP)

Write grouped parts into the opened CSV file

Parameters:

  • out (csv.writer) – A csv.writer object to use for writing to the CSV.

  • board_quantity – Board quantity.

  • columns – Columns list for what data to output.

  • grouped – List of lists of components from the kicad_netlist_reader.

  • output_data – Parts data that will be used to populate the table.

kiabom.write_to_file(f: TextIOWrapper, output_format: str, headers_flag: bool, info_flag: bool, sum_flag: bool, board_quantity: int, columns: list[str], net_obj: Net, parts_file_data: PartsFileData)

Write to the corresponding file the collated data.

Parameters:

  • f – File object

  • output_format – Selected output format.

  • headers_flag – Flag to output headers to the BOM table.

  • info_flag – Flag to output extra info to the end of the file.

  • sum_flag – Flag to output the total price sum after the BOM table.

  • board_quantity – Specify board quantity.

  • columns – Columns to be used when outputting BOM.

  • net_obj – A Net object.

  • parts_file_data – A PartsFileData object.

kiabom.writerow(acsvwriter, columns: list[str])

Override csv.writer’s writerow() to support encoding conversion (initial encoding is utf8)

Parameters:

  • acsvwriter (csv.writer) – A csv.writer object used to write the columns list.

  • columns – A list of string values to write as a row.

Classes

class kiabom.BaseNet(input_xml: str, excludeBOM: bool, excludeBoard: bool)

Base Net class where Net and NetDNP inherit their shared members

Parameters:

  • input_xml – Input XML file name.

  • net – Netlist reader object.

  • components – List of components from the schematic.

  • grouped – List of grouped compoentns.

  • group_count – Number of groups.

  • refdes_groups – List of reference designators from the netlist.

get_components(excludeBOM: bool, excludeBoard: bool)

Get the grouped components. Implemented in BaseNet to force implementation in children.

Parameters:

  • excludeBOM – Boolean value of whether to include symbols with the exclude from BOM property set.

  • excludeBoard – Boolean value of whether to include symbols with the exclude from Board property set.

Raises:

NotImplementedError – Error raised when function not implemented in children.

get_refdes_from_net(grouped: list[list[comp]]) → list[list[str]]

Get reference designators from KiCAD netlist reader

Parameters:

grouped – List of kicad_netlist_reader component groups.

Returns:

A list of reference designator groups.

class kiabom.BaseParts(supplier: str, net_obj: Net | NetDNP, return_empty: bool, currency: str, ignore_mpns: list, board_quantity: int)

Base class for the Parts and PartsDNP classes containing KiCost part details as lists.

get_currency_symbol_list(currency: str, order_codes: list[str]) → list[str]

Get a list with all the currency values for the parts.

Parameters:

  • currency – Currency string, e.g. GBP, USD, or EUR.

  • order_codes – Order codes list.

Returns:

A list with the currency symbols where a valid order code was found.

get_manufacturer_from_kicost(parts: list[PartGroup], supplier: str) → list[str]

Get the manufacturer from the returned KiCost parts list.

Parameters:

  • parts – List of parts returned from KiCost.

  • supplier – Supplier name.

Returns:

List of the manufacturers with blanks when none was found.

get_order_code_from_kicost(parts: list[PartGroup], supplier: str) → list[str]

Get the order code from the returned KiCost parts list.

Parameters:

  • parts – List of parts returned from KiCost.

  • supplier – Supplier name.

Returns:

List of the order codes with blanks when none was found.

get_price_from_kicost(quantity: list[str], price_tiers: list[dict]) → list[str]

Get the price from the price tiers based on the quantity.

Parameters:

  • quantity – Quantity from the number of parts in the group.

  • price_tiers – Price tiers returned from the API.

Returns:

List of the prices in string format.

get_price_tiers_from_kicost(parts: list[PartGroup], supplier: str) → list[dict]

Get the price tiers from the returned parts list.

Parameters:

  • parts – List of parts returned from KiCost.

  • supplier – Supplier string.

Returns:

List of price tiers.

get_quantity_from_kicost(parts: list[PartGroup], board_quantity: int) → list[str]

Get the quantity from the returned KiCost parts.

Parameters:

  • parts – List of parts returned from KiCost.

  • board_quantity – Specified board quantity from the options.

Returns:

List of all the quantities detected by KiCost.

get_refs_from_kicost(parts: list[PartGroup]) → list[list[str]]

Get reference designators from KiCost API. Also sorting them so that the output is a bit more similar to the netlist reader when debugging.

Parameters:

parts – List of PartGroup objects.

Returns:

List of reference groups.

get_stock_from_kicost(parts: list[PartGroup], supplier: str) → list[str]

Get the stock from the returned KiCost parts list.

Parameters:

  • parts – List of parts returned from KiCost.

  • supplier – Supplier name.

Returns:

List of the stock with blanks when none was found.

get_supplier_list(supplier: str, order_codes: list[str]) → list[str]

Get the supplier list for all parts returned from KiCost.

Parameters:

  • supplier – Supplier text.

  • order_codes – List of the order codes.

Returns:

List of the suppliers for all the returned parts.

keep_only_components_in_netlist(components: OrderedDict, net_refs_groups: list[list[str]]) → OrderedDict

Reads all the components KiCost found from the XML and keeps only those that were read initially from net.getInterestingComponents().

Parameters:

  • components – OrderedDict of components and their information.

  • net_refs_groups – List of the reference groups from the netlist reader.

Returns:

OrderedDict of components and their information but only those that match the ones from the netlist reader.

match_api_parts_list_with_reader_list(api_refs_groups: list[list[str]], net_refs_groups: list[list[str]], api_parts_list: list[PartGroup]) → list[PartGroup]

Match the KiCost API result with the KiCAD net list reader

Parameters:

  • api_refs_groups – List of the reference designator groups from KiCost.

  • net_refs_groups – List of the reference designator groups from KiCAD.

  • api_parts_list – List of the parts returned from KiCost.

Returns:

A PartsGroup list where all parts match the KiCAD netlist reader sequence.

search_parts_kicost(net_obj: Net | NetDNP, supplier: str, currency: str, ignore_mpns: list) → list[PartGroup]

Search the distributor for the parts given by the input XML file.

Parameters:

  • net_obj – Net object containing relevant information from the kicad_netlist_reader.

  • supplier – Supplier text.

  • currency – Currency code.

  • ignore_mpns – List of strings to ignore if found in the MPN field.

Returns:

Parts data as an OrderedDict.

set_blank_val_to_ignore_mpns(components: OrderedDict, ignore_mpns: list[str]) → OrderedDict

Set the ‘manf#’ value in the components dict to blank so that the ignore_mpns parts are skipped by the KiCost API.

Parameters:

  • components – OrderedDict of components and their information.

  • ignore_mpns – List of the MPN strings to not search for.

Returns:

A list with the MPN values that should be ignored set to blank.

class kiabom.BasePartsFileData(primary_parts_obj: Parts | PartsDNP, secondary_parts_obj: Parts | PartsDNP)

Class containing the file data that is common between DNP and non-DNP parts. Has data from both primary and secondary suppliers.

Parameters:

  • manufacturer – Manufacturer list.

  • primary_order_codes – Primary order codes list.

  • primary_supplier – Primary supplier list containing the primary supplier string.

  • secondary_order_codes – Secondary order codes list.

  • secondary_supplier – Secondary supplier list containing the secondary supplier string.

  • price – List containing the prices for each part.

  • currency_symbol – Currency symbol for each part.

class kiabom.Net(input_xml: str, excludeBOM: bool, excludeBoard: bool)

Contains data read by the netlist reader.

Parameters:

dnp – NetDNP object containing information about DNP components.

get_components(excludeBOM: bool, excludeBoard: bool) → list[comp]

Get the grouped components

Parameters:

  • excludeBOM – Boolean value of whether to include symbols with the exclude from BOM property set.

  • excludeBoard – Boolean value of whether to include symbols with the exclude from Board property set.

Returns:

List of grouped kicad_netlist_reader components.

class kiabom.NetDNP(input_xml: str, excludeBOM: bool, excludeBoard: bool)

Contains data read by the netlist reader for DNP components.

extract_dnp(component_list: list[comp]) → list[comp]

Extract the DNP components from a comp list.

Parameters:

component_list – List of components from the kicad_netlist_reader.

Returns:

A list of the DNP components.

get_components(excludeBOM: bool, excludeBoard: bool) → list[comp]

Get the grouped components and extract the DNP components.

Parameters:

  • excludeBOM – Boolean value of whether to include symbols with the exclude from BOM property set.

  • excludeBoard – Boolean value of whether to include symbols with the exclude from Board property set.

Returns:

List of grouped DNP kicad_netlist_reader components.

class kiabom.Parts(supplier: str, net_obj: Net, return_empty: bool, currency: str, ignore_mpns: list, board_quantity: int)

Contains non-DNP parts data retrieved by KiCost for a specific supplier.

Parameters:

dnp – A PartsFileDataDNP object instance.

class kiabom.PartsDNP(supplier: str, net_obj: NetDNP, return_empty: bool, currency: str, ignore_mpns: list, board_quantity: int)

Contains DNP parts data retrieved by KiCost for a specific supplier

class kiabom.PartsFileData(primary_parts_obj: Parts, secondary_parts_obj: Parts)

Contains data of the parts as simple lists for outputting.

Parameters:

dnp – A PartsFileDataDNP object instance.

class kiabom.PartsFileDataDNP(primary_parts_obj: PartsDNP, secondary_parts_obj: PartsDNP)

Contains DNP CSV data of the DNP parts