hcautomation 1.0.2

A Python package for automating LMG processes

hcautomation

A Windows-focused automation toolkit for Enterprise Reporting downloads, Excel refresh/macro workflows, Outlook email automation, and DataFrame/file utilities.

Features

• Automates Enterprise Reporting exports with Selenium + Edge
• Supports direct export and filter-based export flows
• Includes typed filter configuration via FilterSpec
• Refreshes Excel workbooks and runs VBA macros through COM
• Sends Outlook emails with attachments
• Cleans and transforms pandas DataFrames
• Loads and validates Product List (PL) files
• Provides small file/date utility helpers

Installation

pip install hcautomation

Requirements

This package depends on both Python packages and local Windows applications.

Python dependencies

• selenium
• rsa
• pandas
• numpy
• pywin32

System requirements

• Windows
• Microsoft Edge
• Compatible Edge WebDriver / Selenium setup
• Microsoft Excel
• Microsoft Outlook

Quick Start

Download a report directly

from hcautomation import ERDownloader

downloader = ERDownloader(download_dir=r"C:\Temp")
downloader.er(
    bookmark_name="Daily Sales",
    save_path=r"C:\Reports\daily_sales.csv"
)

Download a report with filters

from hcautomation import ERDownloader, FilterSpec

downloader = ERDownloader()

date_filter = FilterSpec(
    filter_name="Date",
    start_date="01/03/2026",
    end_date="31/03/2026"
)

downloader.er(
    bookmark_name="Daily Sales",
    save_path=r"C:\Reports\daily_sales.xlsx",
    direct_export=False,
    filter_spec=date_filter
)

Use helper utilities

from hcautomation import Helpers

helpers = Helpers()

---

Exceptions

The package defines the following custom exceptions for Enterprise Reporting flows:

• ERDownloaderError
• LoginTimeoutError
• BookmarkNotFoundError
• FilterNotFoundError
• DownloadTimeoutError
• ConfirmationTimeoutError

---

API Reference

FilterSpec

Dataclass used to define filter inputs before applying them in Enterprise Reporting.

Signature

FilterSpec(
    filter_name: str,
    start_date: str | None = None,
    end_date: str | None = None,
    single_value_filter: str | None = None
)

Purpose

• Use filter_name="Date" with both start_date and end_date
• Use single_value_filter for supported single-value filters such as Territory or Location Code

Arguments

Argument	Required	Type	Default	Description
filter_name	Yes	str	—	Name of the filter
start_date	Conditional	str | None	None	Required when filter_name == "Date"
end_date	Conditional	str | None	None	Required when filter_name == "Date"
single_value_filter	Conditional	str | None	None	Required for non-date single-value filters

Example

date_filter = FilterSpec(
    filter_name="Date",
    start_date="01/03/2026",
    end_date="31/03/2026"
)

territory_filter = FilterSpec(
    filter_name="Territory",
    single_value_filter="UAE"
)

---

ERDownloader

Automates Enterprise Reporting login, bookmark navigation, filtering, export, download detection, and final file movement.

ERDownloader(download_dir=None)

Initializes the downloader and loads encrypted credentials.

Arguments

Argument	Required	Type	Default	Description
download_dir	No	str | Path | None	User Downloads folder	Temporary download directory

Example

downloader = ERDownloader(download_dir=r"C:\Reports\Temp")

---

er(bookmark_name, save_path, direct_export=True, filter_spec=None, num_filters=10, concept="Home Center", user="Omkar")

Main public method that runs the full Enterprise Reporting export workflow.

Arguments

Argument	Required	Type	Default	Description
bookmark_name	Yes	str	—	Name of the bookmark/report
save_path	Yes	str | Path	—	Final output path ending in .csv or .xlsx
direct_export	No	bool	True	Use direct export flow
filter_spec	Conditional	FilterSpec | None	None	Required when direct_export=False
num_filters	No	int	10	Number of filter rows to scan
concept	No	str	"Home Center"	Concept folder name
user	No	str	"Omkar"	User folder name

Example

from hcautomation import ERDownloader, FilterSpec

downloader = ERDownloader(download_dir=r"C:\Temp")

date_filter = FilterSpec(
    filter_name="Date",
    start_date="01/03/2026",
    end_date="31/03/2026"
)

downloader.er(
    bookmark_name="Daily Sales Report",
    save_path=r"C:\Reports\daily_sales.csv",
    direct_export=False,
    filter_spec=date_filter,
    num_filters=10,
    concept="Home Center",
    user="Omkar"
)

---

Helpers

Collection of utility methods for dataframe cleanup, Excel COM automation, Outlook mail generation, PL file loading, and file/date checks.

Helpers()

Creates a helper instance.

Arguments

Argument	Required	Type	Default	Description
None	—	—	—	No constructor parameters

---

strip_chars_v3(df, column_names)

Removes non-numeric characters except - and . from selected columns, then converts them to float.

Arguments

Argument	Required	Type	Default	Description
df	Yes	pd.DataFrame	—	DataFrame to modify
column_names	Yes	iterable	—	Columns to clean

Returns

• Cleaned pd.DataFrame
• Original dataframe copy if conversion fails

Example

helpers = Helpers()
df = helpers.strip_chars_v3(df, ["Sales", "Margin"])

---

call_macro(excel_file_path, macro_name)

Opens an Excel workbook, runs one or more VBA macros, saves, and closes it.

Arguments

Argument	Required	Type	Default	Description
excel_file_path	Yes	str	—	Workbook path
macro_name	Yes	iterable	—	Macro names to execute

Returns

• 0 if the workbook cannot be opened
• Otherwise no explicit return value

Notes

This method references self.logger, so it expects a logger attribute to exist on the instance before use.

---

refresh_excel(excel_file_path)

Refreshes all workbook connections/queries and saves the workbook.

Arguments

Argument	Required	Type	Default	Description
excel_file_path	Yes	str	—	Workbook path

Returns

• 0 if the workbook cannot be opened
• Otherwise no explicit return value

Notes

This method references self.logger, so it expects a logger attribute to exist on the instance before use.

---

refresh_excel_safe(excel_file_path)

Safer Excel refresh helper with explicit COM initialization and cleanup.

Arguments

Argument	Required	Type	Default	Description
excel_file_path	Yes	str	—	Workbook path

---

send_mail(to_list, cc_list, subject, attachments=[], html_body='', body='', send_flag=False)

Creates an Outlook email, optionally attaches files, and either displays or sends it.

Arguments

Argument	Required	Type	Default	Description
to_list	Yes	str	—	To recipients
cc_list	Yes	str	—	CC recipients
subject	Yes	str	—	Email subject
attachments	No	list	[]	Attachment paths
html_body	No	str	''	HTML body
body	No	str	''	Plain text body
send_flag	No	bool	False	Send immediately if True, otherwise display draft

Example

helpers.send_mail(
    to_list="[e-mail]",
    cc_list="[e-mail]",
    subject="Daily Report",
    attachments=[r"C:\Reports\daily_sales.xlsx"],
    body="Please find the report attached.",
    send_flag=True
)

---

process_semantic_dumps(path, col_rename_map=None, sheet_name=None, skiprows=2, date_cols=(), numeric_cols=(), errors='raise')

Reads a semantic dump Excel file, normalizes columns, renames them, and applies optional date/numeric conversion.

Arguments

Argument	Required	Type	Default	Description
path	Yes	str | pd.ExcelFile	—	Excel file path or pd.ExcelFile object
col_rename_map	Yes	Mapping[str, str] | None	None	Column rename mapping
sheet_name	No	str | int | None	None	Sheet name or index
skiprows	No	int	2	Number of rows to skip
date_cols	No	sequence	()	Columns to convert to datetime
numeric_cols	No	sequence	()	Columns to convert to numeric
errors	No	str	'raise'	Conversion error handling behavior

Returns

• Processed pd.DataFrame
• None if opening fails with PermissionError

Raises

• ValueError
• KeyError

---

clean_exit(message="\nPress Ctrl+C to exit...")

Prints a message and blocks until the user stops the process with Ctrl+C.

Arguments

Argument	Required	Type	Default	Description
message	No	str	"\nPress Ctrl+C to exit..."	Message shown before waiting

---

fetch_pl_files(terr, omni_letter='O', pl_columns=('skuCode','concept'), col_rename_map=None, marketplace=False, dtype_dict=None, fetch_last_month=False)

Fetches the latest Product List file for a territory, with fallback to the previous month when needed.

Arguments

Argument	Required	Type	Default	Description
terr	Yes	str	—	Territory code: QAT, UAE, KWT, KSA, OMN, BAH, or EGP
omni_letter	No	str	'O'	Drive letter prefix
pl_columns	No	Sequence[str]	('skuCode', 'concept')	Columns to read from the CSV
col_rename_map	No	Mapping[str, str] | None	None	Optional rename mapping
marketplace	No	bool	False	Use marketplace PL path if True
dtype_dict	No	Mapping[str, str] | None	None	Optional dtype mapping for read_csv
fetch_last_month	No	bool	False	Force previous-month lookup

Returns

(df, latest_pl_file)

Raises

• ValueError
• FileNotFoundError

Example

df, file_path = helpers.fetch_pl_files(
    terr="UAE",
    marketplace=False,
    pl_columns=("skuCode", "concept", "createdTime")
)

---

is_file_updated_today(file_path, raise_on_fail=True)

Checks whether a file exists and whether it was modified today.

Arguments

Argument	Required	Type	Default	Description
file_path	Yes	str	—	File path to check
raise_on_fail	No	bool	True	Raise instead of returning False on failure

Returns

• True if updated today
• False if not updated today and raise_on_fail=False

Raises

• FileNotFoundError

---

define_cust_type(df, cust_id='Customer ID')

Classifies each customer as New or Repeat by comparing transaction date and first transaction date.

Arguments

Argument	Required	Type	Default	Description
df	Yes	pd.DataFrame	—	Input dataframe
cust_id	No	str	'Customer ID'	Customer ID column name

Returns

• pd.DataFrame with a new_repeat column

Raises

• KeyError
• AssertionError

---

get_latest_file(path, typ='c')

Returns the latest file matching a glob pattern based on creation or modification time.

Arguments

Argument	Required	Type	Default	Description
path	Yes	str | Path	—	Glob pattern
typ	No	str	'c'	'c' for creation time, 'm' for modification time

Returns

• Latest matching file path

Raises

• ValueError

Example

latest = helpers.get_latest_file(r"C:\Reports\*.xlsx", typ="m")

---

Notes

• This package is Windows-specific for COM-based Excel and Outlook automation.
• Enterprise Reporting automation depends on the current ER UI structure and labels.
• call_macro() and refresh_excel() reference self.logger, but Helpers does not create one internally.
• Several helper methods are defined without a self parameter in the current code, which means they behave more like static utilities unless adjusted in the package implementation.

License

Add your project license here, for example:

MIT