Metadata-Version: 2.4
Name: pandaspro
Version: 1.4.1
Summary: Upgraded pandas package for easier dataframe operations
License: MIT
License-File: LICENSE
Author: Shiyao Wang
Author-email: sw1016@georgetown.edu
Requires-Python: >=3.8,<3.14
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Dist: PyPDF2 (>=3.0.1)
Requires-Dist: jinja2 (>=3.1.4)
Requires-Dist: numpy (>=1.26.0)
Requires-Dist: openpyxl (>=3.1.5)
Requires-Dist: pandas (>=2.2.1)
Requires-Dist: python-dateutil (>=2.8.2)
Requires-Dist: pyyaml (>=6.0)
Requires-Dist: tabulate (>=0.9.0)
Requires-Dist: termcolor (>=2.4.0)
Requires-Dist: xlwings (>=0.31.10)
Project-URL: Homepage, https://github.com/Unicell-Organization/pandaspro
Description-Content-Type: text/markdown

# 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

```python
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:

```python
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.

```python
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.

## 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.

