pandaspro

pandas with friendlier dataframe methods and Excel export / formatting helpers.

pip install pandaspro

See CHANGELOG.md for what changed in each version, and df.cpdhelp() for the dataframe shortcuts.

Data assembly: cpdBaseFrame and cpdDatabaseC

The two halves of assembling a project's data:

• cpdBaseFrame — dated system extracts. One folder of files named by date (SOB_20261001.csv); decorate a class and load a version with X(version="latest"). The data is produced elsewhere and only read here.
• cpdDatabaseC — hand-maintained lists. One folder of JSON files named by list (modules/clients.json) plus a browser editor; decorate a store class and one class per list. The data is maintained by people in the published page.

cpdDatabaseC

from mylists import MyLists, Clients

MyLists.publish()          # creates <folder>/mylists.html and modules/*.json (data is never overwritten)
MyLists.open()             # opens the editor in Edge / Chrome; "Open folder" -> pick <folder>

Clients.frame()            # rows as a DataFrame
MyLists.list()             # every module: id, title, group, live, rows, revision, saved_at
MyLists.check()            # one line per module: filled? live? same as its old source?

CountryGroups.import_source()   # rows from the old Excel into the module (not live yet)
CountryGroups.compare()         # empty frame = module and Excel agree
CountryGroups.set_live()        # from now on read_live() returns the module

mylists is the example shipped in pandaspro/cpddatabasec/example/: copy mylists/ into your project, rename the store, keep or replace the three example lists, add your own. Declaring a store and a list:

from pandaspro import cpdDatabaseC, cpdField as field

@cpdDatabaseC(name="MyLists", package="myproject", editor="mylists.html")
class MyLists:
    @classmethod
    def get_path(cls):                       # or path="..." in the decorator
        return os.environ["MYLISTS_DIR"]     # per machine, never a hard-coded path in the repo

@MyLists.module("clients", title="Clients", group="Reference", key=["code"])
class Clients:
    code = field(required=True, help="Short code, unique")
    name = field(required=True)
    tier = field(type="select", options=["A", "B", "C"])

Add a list = add a decorated class. Add a field = add a line (publish() refreshes the definition, rows stay). Change the page = pass editor_source="your.html" (start from a copy of pandaspro/cpddatabasec/editor.html).

Word reports: WordReport

Take Word reports apart into sections, paragraphs and tables, check that nothing was lost, put several together and write one .docx with a consistent layout. Standard library only.

import pandaspro as cpd

a = cpd.WordReport.read("part_a.docx")
b = cpd.WordReport.read("part_b.docx")

a.preview()                 # numbered outline: S1 sections, P3 paragraphs, T2 tables
a.preview_html()            # rendered page in the browser, with the check on top
print(a.check())            # characters, digits, every number, footnotes, tables vs the source

table = a.tables[0]
table.title, table.header_rows, table.notes, table.footnotes
table.frame                 # DataFrame; table.to_frame(numeric=True) parses the numbers

merged = cpd.WordReport.merge(a, b, titles=["Part A", "Part B"])
merged.to_docx("out/combined.docx")   # written, read back and compared; raises on any difference

What is kept: the text, bold / italic / underline / strike, colour, highlight, super and subscript, links, footnotes and endnotes, bullets and numbering, merged cells, header rows, cell shading, pictures and text boxes. Fonts and font sizes are dropped on purpose: the output uses one layout. Charts and diagrams cannot be carried; a red placeholder marks their position and report.warnings lists them. The table of contents, page headers / footers and comments are not read.

Table titles ("Table 1 ...", the Caption style) and notes ("Note:", "Source:", "a/ ...") are found by rule. When a rule guesses wrong, pass title_pattern= / note_pattern= to read(), or move the paragraphs yourself: section.blocks, table.title and table.notes are ordinary lists.

report.to_dict() / to_json() / WordReport.from_json() expose the whole structure.

Some Word files lay a whole page out as one table: a row of running text, empty spacer rows, a "Table 1 ..." row, the real header and data rows, another title row. read() takes such layout tables apart into paragraphs and separate tables and drops the empty rows and columns (unpack_layout=False keeps them as they are; report.unpacked says how many were found).

Merging

merged = cpd.WordReport.merge(a, b, tables_last=True, tables_heading="Tables", number_tables=True)

tables_last puts the text of all reports first (headings and paragraphs, in order) and all their tables after it. number_tables gives the table titles "Table 1.", "Table 2." ... in that order: a number a title already has ("Table A1:") is replaced, a table without a title gets "Table N"; nothing else in the titles changes. report.number_tables(prefix="Table", sep=".") does the same on any report.

Reviewing before writing

merged.review_html()                     # opens a page: keep / drop, rename, title and subtitle
merged = merged.apply_review(r'''{...}''')   # the line the page's "Copy result" button gives

Every section, paragraph and table on the page has a checkbox; headings and table titles are editable; a title and subtitle can be typed at the top. Cells and numbers cannot be changed there. apply_review() takes the JSON as a dict, a string or the path of the downloaded review.json and returns a new report; check() still passes, with the dropped text counted.

Writing into a template

to_docx(template=...) writes into your own blank .docx / .dotx: its page header and footer, page size and margins, theme and styles are kept, and the report goes under whatever its body holds (a title line, empty lines that leave room for a banner). keep_template_body=False starts from an empty body. fill={"XXX": "Region A", "MM DD, YYYY": "September 30, 2026"} replaces placeholders in the template body, page headers and footers, also when Word split them over several runs, and removes their highlight. A placeholder the template does not have gives a warning (fill_missing="error" raises, "ignore" stays quiet). WordReport.inspect_template(path) lists the template's style names, its highlighted placeholders and its body text. Headings, captions and tables take the template's styles of the same name ("heading 1", "Table Grid" ...). styles= points each part at another style or changes it:

merged.to_docx(
    "out/combined.docx",
    template="blank_template.docx",
    font="Arial",                      # body font; left out, the template's stays
    styles={
        "heading1": "Report Heading",  # a style name in the template
        "heading2": {"font": "Georgia", "size": 13, "color": "1F4E79", "space_before": 18},
        "body": {"east_asia_font": "SimSun", "line_spacing": 1.15},
        "table": {"style": "Grid Table 4", "header_fill": "DDEBF7", "borders": "horizontal"},
        "table_header": {"bold": True},
    },
)

Roles: body, heading1 … heading9, title, subtitle, list, quote, caption, table_title, table_text, table_header, table_note, footnote, endnote, table. Paragraph options: font, east_asia_font, size, bold, italic, underline, color, all_caps, small_caps, letter_spacing (points, negative is narrower), align, space_before / space_after (points), line_spacing, indent / first_line (inches), keep_with_next, page_break_before, and style to start from a named style. Table options: style, borders (grid, horizontal, outside, none), border_color, border_size, header_fill, header_color (text in header rows), header_height / row_height (inches), align, first_column, banded_rows, keep_together (default on). An option that sets bold, italic or underline on a role also overrides what the source runs carried. A name the template does not have raises an error that lists the names it does have. page=, landscape= and margin= override the template's page setup only when given.

preset="compact" removes the space before and after every paragraph (headings and titles too), uses single line spacing and sets paragraphs apart with an empty line instead (none under a heading, inside a list or after a table). Title Open Sans 14 bold centred with 8 pt after it, subtitle Open Sans 11 centred and 0.5 pt narrower, headings Open Sans 11 on the left, level 1 in italics; tables in Aptos Narrow 11 with header rows half an inch high, filled 156082, white text; table titles Open Sans, underlined, not bold, numbered "Table 1.", "Table 2." ... and kept with their table; a table stays on one page (it moves to the next page whole when it does not fit; no page break is inserted); the text starts under the page header's banner on every page (margin_top="auto"); headings that start with Annex / Appendix begin a new page (new_page=). styles= is laid over the preset. WordReport.presets() returns a copy of the presets to edit and pass as preset=. title= / subtitle= add those two lines above the report:

merged.to_docx("out/brief.docx", template="blank_template.docx", preset="compact",
               title="Regional Brief", subtitle="As of September 30, 2026",
               fill={"XXX": "Region A", "MM DD, YYYY": "September 30, 2026"})

Versions and releases

All work happens on master. A version is a tag on master (v1.3.1); there are no version branches. The version number lives in one place, pyproject.toml.

• While you work: add a line under Unreleased in CHANGELOG.md for anything a user can notice.
• To release: python release.py 1.3.2 (add --dry-run to rehearse). It checks the tree, runs the tests, sets the version, dates the changelog section, commits, tags and pushes. The pushed tag makes GitHub Actions build the package and publish it to PyPI.
• Every push to master runs the tests on GitHub.
• A machine that produces reports should sit on a tag, not on every push: git fetch --tags then git checkout v1.3.2.
• Version numbers: last digit for fixes and small additions, middle digit for new features, first digit when existing calls stop working.