babilonia.accounting#

Brazil-specific accounting classes and tax reference constants.

Provides data classes for parsing and analyzing bank statements from Banco do Brasil and Nubank, computing cash flow summaries, managing budget records, and loading NFSe XML invoices. Module-level constants hold the 2025 INSS and IRRF progressive tax tables.

Classes

BBCDB([name, alias])

Parses Banco do Brasil CDB investment statement text files.

Budget([name, alias])

A record table for managing budget items.

CashFlow([name, alias])

A primitive class for handling Cash flow analysis

CashFlowBBCC([name, alias])

A class for handling CSV data from Banco do Brasil Conta Corrente.

CashFlowBBCCPJ([name, alias])

Class for handling BB-CC for PJ accoung CSV data.

CashFlowBBPP([name, alias])

Class for handling BB-PP CSV data.

CashFlowNUCredit([name, alias, invert_sign])

A class for handling CSV data exported from Nubank Cartão de Crédito (Nubank credit card) invoices.

NFSe([name, alias])

Class for handling NFSe XML data.

NFSeColl([base_object, name, alias])

A collection of NFSe objects.
class babilonia.accounting.Budget(name='MyBudget', alias='Bud')[source]#

Bases: RecordTable

A record table for managing budget items.

Extends RecordTable to track revenues and expenses with support for contract grouping, payment status, due dates, and file attachments. Signed totals and per-status or per-contract summaries are recomputed automatically on update.

update()[source]#

Refresh all mutable attributes based on data (including paths).

set_data(input_df)[source]#

Set RecordTable data from incoming dataframe. Expected to be incremented downstream.

Parameters:

input_df (dataframe) – incoming dataframe

Returns:

None

Return type:

None

get_summary_by_type()[source]#
get_summary_by_status(filter_df=True)[source]#
get_summary_by_contract(filter_df=True)[source]#
get_summary_by_tags(filter_df=True)[source]#
static parse_annual_budget(year, budget_df, freq_field='Freq')[source]#
class babilonia.accounting.CashFlow(name='CashFlow', alias='CF')[source]#

Bases: DataSet

A primitive class for handling Cash flow analysis

Cashflow Analysis Example
from babilonia.accounting import CashFlow

# create an empty class
cf = CashFlow()

# set the file for CSV
file_csv = "path/to/file.csv" # [change this]

# load data
cf.load_data(file_csv)

# call method
dc = cf.cashflow_analysis(df=cf.data, category="Custeio")

# print data
print(dc["monthly"])
print(dc["yearly"])
load_data(file_data)[source]#

Load data from file.

Parameters:

file_data (str) – file path to data.

static get_cashflow_analysis(df, category=None)[source]#

Perform cash flow analysis with monthly and yearly aggregation.

This method classifies cash flows into inputs and outputs, aggregates values on a monthly and yearly basis, and computes cumulative balances. The analysis is fully independent from class state and inheritance behavior.

Parameters:

  • df (pandas.DataFrame) – Input cash flow data containing at least the columns Data, Categoria and Valor.

  • category (str or None) – Optional category filter. If None, all categories are grouped under "Geral".

Returns:

Dictionary with monthly and yearly cash flow summaries.

Return type:

dict

static compute_oir(df, input_field='Entradas', output_field='Saidas')[source]#
static enrich_time_index(df)[source]#

Add year and year-month time indices to the cash flow data.

This method extracts the calendar year and a YYYY-MM monthly identifier from the Data column.

Parameters:

df (pandas.DataFrame) – Input cash flow data.

Returns:

Copy of the input data with additional Ano and Mes columns.

Return type:

pandas.DataFrame

static classify_flows(df)[source]#

Classify cash flows as inputs or outputs.

Positive or zero values are classified as "In" and negative values as "Out".

Parameters:

df (pandas.DataFrame) – Cash flow data containing a Valor column.

Returns:

Copy of the input data with an additional Flow column.

Return type:

pandas.DataFrame

static filter_category(df, category)[source]#

Filter cash flow data by category.

If no category is provided, all records are grouped under the default category "Geral".

Parameters:

  • df (pandas.DataFrame) – Cash flow data.

  • category (str or None) – Category name used to filter the data.

Returns:

Tuple containing the filtered data and the resolved category name.

Return type:

tuple

static get_monthly_summary(df, category)[source]#

Compute monthly cash flow summaries for each year.

This method aggregates cash flow inputs and outputs on a monthly basis, ensures that all calendar months are present, and computes annual cumulative balances.

Parameters:

  • df (pandas.DataFrame) – Cash flow data enriched with time indices and flow classification.

  • category (str) – Category name associated with the analysis.

Returns:

Monthly cash flow summary table.

Return type:

pandas.DataFrame

static get_yearly_summary(df_monthly, category)[source]#

Compute yearly cash flow summaries.

This method aggregates monthly cash flow data into yearly totals and computes cumulative balances across years.

Parameters:

  • df_monthly (pandas.DataFrame) – Monthly cash flow summary table.

  • category (str) – Category name associated with the analysis.

Returns:

Yearly cash flow summary table.

Return type:

pandas.DataFrame

static get_cashflow_report(df, year=None, initial_cash=None)[source]#

Build a yearly cash flow panel and summary by category.

Parameters:

  • df (pandas.DataFrame) – Cash flow DataFrame containing transactional data with date, category, and value information compatible with the enrich_time_index, classify_flows, and cashflow_analysis methods.

  • year (int, optional) – Year to be analyzed. If None, the current calendar year (local time) is used.

  • initial_cash (float, optional) – Initial account balance at the beginning of the selected year. If None, defaults to 0.0.

Returns:

Dictionary containing: "Pannel": monthly cash flow panel with totals, per-category flows, and running balance. "Summary": yearly summary by category with total, mean, and percentage contribution to total inflows.

Return type:

dict

static format_currency(x: float)[source]#
static format_currency_columns(df: pandas.DataFrame, columns: list[str]) → pandas.DataFrame[source]#

Return a copy of df with selected numeric columns formatted as strings.

class babilonia.accounting.CashFlowBBCC(name='CashFlowBBCC', alias='CFBBCC')[source]#

Bases: CashFlow

A class for handling CSV data from Banco do Brasil Conta Corrente.

Script example
from babilonia.accounting import CashFlowBBCC

# create an empty class
cf = CashFlowBBCC()

# set the file for CSV
file_csv = "path/to/file.csv" # [change this]

# load data
cf.load_data(file_csv)

# standardize data
cf.standardize()

# print data
print(cf.data.head(10))

# save data
file_out = "path/to/output.csv" # [change this]
cf.data.to_csv(file_out, sep=";", index=False)
load_data(file_data)[source]#

Load raw data from bank CSV statement

Parameters:

file_data (str or Path) – Bank statement CSV file path

Returns:

None

Return type:

None

standardize(force=False)[source]#

Standardize data into canonical format.

Parameters:

force – Rebuild parsed data even if it exists

parse_data(df=None)[source]#

Parse data to canonical format

Parameters:

df (pandas.DataFrame) – Optional input data

Returns:

Formated data

Return type:

pandas.DataFrame

parse_date(series)[source]#

Parse BB date field from DD/MM/YYYY to datetime.

Parameters:

series (pandas.Series) – String series

Returns:

Datetime series

Return type:

pandas.Series

parse_valor(series)[source]#

Convert Valor field to float.

Examples

Input

Output

5.000,00

5000.00

-403,00

-403.00
Parameters:

series (pandas.Series) – String series

Returns:

Value series

Return type:

pandas.Series

apply_drops(df)[source]#

Filter dataframe for parsing

Parameters:

df (pandas.DataFrame) – Input data

Returns:

Output data

Return type:

pandas.DataFrame

normalize_columns(df)[source]#

Normalize legacy / alternative column names to the current schema.

Parameters:

df (pandas.DataFrame) – Input data

Returns:

Output data

Return type:

pandas.DataFrame

class babilonia.accounting.CashFlowBBCCPJ(name='CashFlowBBCCPJ', alias='CFBBCCPJ')[source]#

Bases: CashFlowBBCC

Class for handling BB-CC for PJ accoung CSV data.

parse_valor(series)[source]#

Convert Valor field to float.

Examples

Input

Output

5.000,00 C

5000.00

-403,00 D

-403.00
Parameters:

series (pandas.Series) – String series

Returns:

Value series

Return type:

pandas.Series

apply_drops(df)[source]#

Filter dataframe for parsing

Parameters:

df (pandas.DataFrame) – Input data

Returns:

Output data

Return type:

pandas.DataFrame

class babilonia.accounting.CashFlowBBPP(name='CashFlowBBPP', alias='CFBBPP')[source]#

Bases: CashFlowBBCC

Class for handling BB-PP CSV data.

parse_data(df=None)[source]#

Parse data to canonical format

Parameters:

df (pandas.DataFrame) – Optional input data

Returns:

Formated data

Return type:

pandas.DataFrame

parse_valor(series: pandas.Series) → pandas.Series[source]#

Convert Valor field to float.

Examples

Input

Output

5.000,00 C

5000.00

-403,00 D

-403.00
Parameters:

series (pandas.Series) – String series

Returns:

Value series

Return type:

pandas.Series

apply_drops(df)[source]#

Filter dataframe for parsing

Parameters:

df (pandas.DataFrame) – Input data

Returns:

Output data

Return type:

pandas.DataFrame

class babilonia.accounting.CashFlowNUCredit(name='CashFlowNuCC', alias='CFNUCC', invert_sign=True)[source]#

Bases: CashFlow

A class for handling CSV data exported from Nubank Cartão de Crédito (Nubank credit card) invoices.

Nubank appears to export at least two CSV variants for the same date,title,amount schema:

  • Quoted, Brazilian-formatted values, e.g. "1.234,56" or "- 41,97" (comma decimal separator, dot thousands separator, sometimes a space between the minus sign and the digits).

  • Unquoted, international-formatted values, e.g. 1234.56 or -6722.00 (dot decimal separator, no thousands separator).

parse_valor auto-detects and normalizes both variants.

Note on sign convention: Nubank reports purchases as positive amount and payments/refunds (“Pagamento recebido”) as negative. By default this class inverts that sign when building the canonical Valor field, so purchases become outflows (negative Valor, classified as "Out") and payments/refunds become inflows (positive Valor, classified as "In") — consistent with how CashFlow.classify_flows() is used for the BB accounts. Pass invert_sign=False at construction time to keep Nubank’s raw sign convention instead.

Script example
from babilonia.accounting import CashFlowNuCC

# create an empty class
cf = CashFlowNuCC()

# set the file for CSV
file_csv = "path/to/file.csv"  # [change this]

# load data
cf.load_data(file_csv)

# standardize data
cf.standardize()

# print data
print(cf.data.head(10))

# save data
file_out = "path/to/output.csv"  # [change this]
cf.data.to_csv(file_out, sep=";", index=False)
load_data(file_data)[source]#

Load raw data from the Nubank credit-card CSV export.

Parameters:

file_data (str or Path) – Nubank credit-card CSV file path

Returns:

None

Return type:

None

standardize(force=False)[source]#

Standardize data into canonical format.

Parameters:

force – Rebuild parsed data even if it exists

parse_data(df=None)[source]#

Parse data to canonical format

Parameters:

df (pandas.DataFrame) – Optional input data

Returns:

Formated data

Return type:

pandas.DataFrame

parse_date(series)[source]#

Parse Nubank date field from YYYY-MM-DD to datetime.

Parameters:

series (pandas.Series) – String series

Returns:

Datetime series

Return type:

pandas.Series

parse_valor(series)[source]#

Convert amount field to float, auto-detecting the CSV variant.

Examples

Input

Output (before sign inversion)

"50,50"

50.50

"- 3.784,83"

-3784.83

69.99

69.99

-6722.00

-6722.00
Parameters:

series (pandas.Series) – String series

Returns:

Value series

Return type:

pandas.Series

apply_drops(df)[source]#

Filter dataframe for parsing. No rows are dropped by default; override or extend this to filter specific transactions if needed.

Parameters:

df (pandas.DataFrame) – Input data

Returns:

Output data

Return type:

pandas.DataFrame

normalize_columns(df)[source]#

Normalize alternative / legacy column names to the current schema.

Parameters:

df (pandas.DataFrame) – Input data

Returns:

Output data

Return type:

pandas.DataFrame

class babilonia.accounting.BBCDB(name='BBCDB', alias='BBCDB')[source]#

Bases: DataSet

Parses Banco do Brasil CDB investment statement text files.

Reads the plain-text report exported by BB for CDB DI and CDB Progressivo accounts and splits it into named sections (EXTRATO, SALDOS, DEPOSITOS, RENDIMENTOS), normalizing each into a pandas.DataFrame. The result is stored in self.data as a nested dictionary keyed by account then section name.

load_data(file_data)[source]#

Load data from file.

Parameters:

file_data (str) – file path to data.

static read_txt(file_txt, encoding='cp1252')[source]#
static drop_blank_lines(lines)[source]#
static drop_lines(lines, contains='-')[source]#
static replace_lines(lines, contains='\xa0', relacer=' ')[source]#
static split_accounts(lines)[source]#
static split_sections(dc_data)[source]#
static get_year(lines)[source]#
class babilonia.accounting.NFSe(name='NFSeDataSet', alias='NFSe')[source]#

Bases: DataSet

Class for handling NFSe XML data.

get_metadata()[source]#

Get a dictionary with object metadata.

Returns:

dictionary with all metadata

Return type:

dict

Warning

Metadata does not necessarily include all object attributes.

load_data(file_data)[source]#

Load and parse XML data from the provided file.

Parameters:

file_data (str) – file path to the NFSe XML data.

Returns:

None

class babilonia.accounting.NFSeColl(base_object=<class 'babilonia.accounting.NFSe'>, name='MyNFeCollection', alias='NFeCol0')[source]#

Bases: Collection

A collection of NFSe objects.

Extends Collection to load and aggregate multiple NFSe XML files into a shared catalog, either from a folder or an explicit list of file paths.

load_folder(folder)[source]#

Load NFSe files from a folder

Parameters:

folder (str) – path to folder

Returns:

None

Return type:

None

load_files(lst_files)[source]#

Load NFSe files from a list of files

Parameters:

lst_files (list) – list of paths to files

Returns:

None

Return type:

None