numbers-parser 4.7.0__tar.gz → 4.8.0__tar.gz

numbers_parser-4.8.0/PKG-INFO

@@ -0,0 +1,378 @@
+Metadata-Version: 2.1
+Name: numbers-parser
+Version: 4.8.0
+Summary: Read and write Apple Numbers spreadsheets
+Home-page: https://github.com/masaccio/numbers-parser
+License: MIT
+Author: Jon Connell
+Author-email: python@figsandfudge.com
+Requires-Python: >=3.9,<4.0
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+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: Topic :: Office/Business :: Financial :: Spreadsheet
+Requires-Dist: compact-json (>=1.1.3,<2.0.0)
+Requires-Dist: importlib-resources (>=6.1.1,<7.0.0)
+Requires-Dist: pendulum (>=3.0,<4.0)
+Requires-Dist: protobuf (>=4.21.1,<5.0.0)
+Requires-Dist: python-snappy (>=0.6.1,<0.7.0)
+Requires-Dist: regex (>=2022.9.13,<2023.0.0)
+Requires-Dist: roman (>=3.3,<4.0)
+Requires-Dist: setuptools (>=69.0.3,<70.0.0)
+Requires-Dist: sigfig (>=1.3.2,<2.0.0)
+Project-URL: Documentation, https://github.com/masaccio/numbers-parser/blob/main/README.md
+Project-URL: Repository, https://github.com/masaccio/numbers-parser
+Description-Content-Type: text/markdown
+
+# numbers-parser
+
+[![Test Status](https://github.com/masaccio/numbers-parser/actions/workflows/run-all-tests.yml/badge.svg)](https://github.com/masaccio/numbers-parser/actions/workflows/run-all-tests.yml)[![Security Checks](https://github.com/masaccio/numbers-parser/actions/workflows/codeql.yml/badge.svg)](https://github.com/masaccio/numbers-parser/actions/workflows/codeql.yml)[![Code Coverage](https://codecov.io/gh/masaccio/numbers-parser/branch/main/graph/badge.svg?token=EKIUFGT05E)](https://codecov.io/gh/masaccio/numbers-parser)[![PyPI Version](https://badge.fury.io/py/numbers-parser.svg)](https://badge.fury.io/py/numbers-parser)
+
+`numbers-parser` is a Python module for parsing [Apple Numbers](https://www.apple.com/numbers/)`.numbers` files. It supports Numbers files
+generated by Numbers version 10.3, and up with the latest tested version being 13.2
+(current as of September 2023).
+
+It supports and is tested against Python versions from 3.8 onwards. It is not compatible
+with earlier versions of Python.
+
+## Installation
+
+```bash
+python3 -m pip install numbers-parser
+```
+
+A pre-requisite for this package is [python-snappy](https://pypi.org/project/python-snappy/)
+which will be installed by Python automatically, but python-snappy also requires that the binary
+libraries for snappy compression are present.
+
+The most straightforward way to install the binary dependencies is to use
+[Homebrew](https://brew.sh) and source Python from Homebrew rather than from macOS as described
+in the [python-snappy github](https://github.com/andrix/python-snappy):
+
+For Intel Macs:
+
+```bash
+brew install snappy python3
+CPPFLAGS="-I/usr/local/include -L/usr/local/lib" python3 -m pip install python-snappy
+```
+
+For Apple Silicon Macs:
+
+```bash
+brew install snappy python3
+CPPFLAGS="-I/opt/homebrew/include -L/opt/homebrew/lib" python3 -m pip install python-snappy
+```
+
+For Linux (your package manager may be different):
+
+```bash
+sudo apt-get -y install libsnappy-dev
+```
+
+On Windows, you will need to either arrange for snappy to be found for VSC++ or you can install python
+binary libraries compiled by [Christoph Gohlke](https://www.lfd.uci.edu/~gohlke/pythonlibs/#python-snappy). You must select the correct python
+version for your installation. For example for python 3.11:
+
+```text
+C:\Users\Jon>pip install C:\Users\Jon\Downloads\python_snappy-0.6.1-cp311-cp311-win_amd64.whl
+```
+
+### Quick Start
+
+Reading documents:
+
+```python
+>>> from numbers_parser import Document
+>>> doc = Document("mydoc.numbers")
+>>> sheets = doc.sheets
+>>> tables = sheets[0].tables
+>>> rows = tables[0].rows()
+```
+
+Sheets and tables are iterables that can be indexed using either an
+integer index or using the name of the sheet/table:
+
+```python
+>>> doc.sheets[0].name
+'Sheet 1'
+>>> doc.sheets["Sheet 1"].name
+'Sheet 1'
+>>> doc.sheets[0].tables[0].name
+'Table 1'
+>>> doc.sheets[0].tables["Table 1"].name
+'Table 1'
+```
+
+`Table` objects have a `rows` method which contains a nested list
+with an entry for each row of the table. Each row is itself a list of
+the column values.
+
+```python
+>>> data = sheets["Sheet 1"].tables["Table 1"].rows()
+>>> data[0][0]
+<numbers_parser.cell.EmptyCell object at 0x1022b5710>
+>>> data[1][0]
+<numbers_parser.cell.TextCell object at 0x101eb6790>
+>>> data[1][0].value
+'Debit'
+```
+
+#### Cell Data
+
+Cells are objects with a common base class of `Cell`. All cell types
+have a property `value` which returns the contents of the cell as a
+python datatype. `numbers-parser` uses
+[pendulum](https://pendulum.eustace.io) instead of python’s builtin
+types. Available cell types are:
+
+| Cell type         | value type               | Additional properties                                                                           |
+|-------------------|--------------------------|-------------------------------------------------------------------------------------------------|
+| N<br/>umberCell   | `float`                  |                                                                                                 |
+| TextCell          | `str`                    |                                                                                                 |
+| Ric<br/>hTextCell | `str`                    | See [Bullets and<br/>lists](#bullets-and-lists)                                                 |
+| EmptyCell         | `None`                   |                                                                                                 |
+| BoolCell          | `bool`                   |                                                                                                 |
+| DateCell          | `pend<br/>ulum.datetime` |                                                                                                 |
+| Dur<br/>ationCell | `pend<br/>ulum.duration` |                                                                                                 |
+| ErrorCell         | `None`                   |                                                                                                 |
+| M<br/>ergedCell   | `None`                   | See [Merged<br/>c<br/>ells](https://masaccio.github.io/numbers-parser/#table-cell-merged-cells) |
+
+Cell references can be either zero-offset row/column integers or an
+Excel/Numbers A1 notation. Where cell values are not `None` the
+property `formatted_value` returns the cell value as a `str` as
+displayed in Numbers. Cells that have no values in a table are
+represented as `EmptyCell` and cells containing evaluation errors of
+any kind `ErrorCell`.
+
+```python
+>>> table.cell(1,0)
+<numbers_parser.cell.TextCell object at 0x1019ade50>
+>>> table.cell(1,0).value
+'Debit'
+>>> table.cell("B2")
+<numbers_parser.cell.NumberCell object at 0x103a99790>
+>>> table.cell("B2").value
+1234.5
+>>> table.cell("B2").formatted_value
+'£1,234.50'
+```
+
+#### Pandas Support
+
+Since the return value of `rows()` is a list of lists, you can pass
+this directly to pandas. Assuming you have a Numbers table with a single
+header which contains the names of the pandas series you want to create
+you can construct a pandas dataframe using:
+
+```python
+import pandas as pd
+
+doc = Document("simple.numbers")
+sheets = doc.sheets
+tables = sheets[0].tables
+data = tables[0].rows(values_only=True)
+df = pd.DataFrame(data[1:], columns=data[0])
+```
+
+#### Writing Numbers Documents
+
+Whilst support for writing numbers files has been stable since version
+3.4.0, you are highly recommended not to overwrite working Numbers files
+and instead save data to a new file.
+
+Cell values are written using
+[Table.write()](https://masaccio.github.io/numbers-parser/#numbers_parser.Table.write)
+and `numbers-parser` will automatically create empty rows and columns
+for any cell references that are out of range of the current table.
+
+```python
+doc = Document("write.numbers")
+sheets = doc.sheets
+tables = sheets[0].tables
+table = tables[0]
+table.write(1, 1, "This is new text")
+table.write("B7", datetime(2020, 12, 25))
+doc.save("new-sheet.numbers")
+```
+
+Additional tables and worksheets can be added to a `Document` before
+saving using
+[Document.add_sheet()](https://masaccio.github.io/numbers-parser/#numbers_parser.Document.add_sheet)
+and
+[Sheet.add_table()](https://masaccio.github.io/numbers-parser/#numbers_parser.Sheet.add_table)
+respectively:
+
+```python
+doc = Document()
+doc.add_sheet("New Sheet", "New Table")
+sheet = doc.sheets["New Sheet"]
+table = sheet.tables["New Table"]
+table.write(1, 1, 1000)
+table.write(1, 2, 2000)
+table.write(1, 3, 3000)
+doc.save("sheet.numbers")
+```
+
+#### Styles
+
+`numbers_parser` currently only supports paragraph styles and cell
+styles. The following paragraph styles are supported:
+
+- font attributes: bold, italic, underline, strikethrough
+- font selection and size
+- text foreground color
+- horizontal and vertical alignment
+- cell background color
+- cell indents (first line, left, right, and text inset)
+
+Numbers conflates style attributes that can be stored in paragraph
+styles (the style menu in the text panel) with the settings that are
+available on the Style tab of the Text panel. Some attributes in Numbers
+are not applied to new cells when a style is applied. To keep the API
+simple, `numbers-parser` packs all styling into a single
+[Style](https://masaccio.github.io/numbers-parser/#numbers_parser.Style)
+object. When a document is saved, the attributes not stored in a
+paragraph style are applied to each cell that includes it.
+
+Styles are read from cells using the
+[Cell.style](https://masaccio.github.io/numbers-parser/#numbers_parser.Cell.style)
+propert and you can add new styles with
+[Document.add_style](https://masaccio.github.io/numbers-parser/#numbers_parser.Document.add_style).
+
+Since `Style` objects are shared, changing `Cell.style.font_size`
+will have the effect of changing the font size for that style and will
+in turn affect the styles of all cells using that style.
+
+#### Cell Data Formatting
+
+Numbers has two different cell formatting types: data formats and custom
+formats.
+
+Data formats are presented in Numbers in the Cell tab of the Format pane
+and are applied to individual cells. Like Numbers, `numbers-parsers`
+caches formatting information that is identical across multiple cells.
+You do not need to take any action for this to happen; this is handled
+internally by the package. Changing a data format for cell has no impact
+on any other cells.
+
+Cell formats are changed using
+[Table.set_cell_formatting](https://masaccio.github.io/numbers-parser/#numbers_parser.Table.set_cell_formatting):
+
+```python
+table.set_cell_formatting("C1", "date", date_time_format="EEEE, d MMMM yyyy")
+table.set_cell_formatting(0, 4, "number", decimal_places=3, negative_style=NegativeNumberStyle.RED)
+```
+
+Custom formats are shared across a Document and can be applied to
+multiple cells in multiple tables. Editing a custom format changes the
+appearance of data in all cells that share that format. You must first
+add a custom format to the document using
+[Document.add_custom_format](https://masaccio.github.io/numbers-parser/#numbers_parser.Document.add_custom_format)
+before assigning it to cells using
+[Table.set_cell_formatting](https://masaccio.github.io/numbers-parser/#numbers_parser.Table.set_cell_formatting):
+
+```python
+long_date = doc.add_custom_format(name="Long Date", type="date", date_time_format="EEEE, d MMMM yyyy")
+table.set_cell_formatting("C1", "custom", format=long_date)
+```
+
+A limited number of currencies are formatted using symbolic notation
+rather than an ISO code. These are defined in
+`numbers_parser.currencies` and match the ones chosen by Numbers. For
+example, US dollars are referred to as `US$` whereas Euros and British
+Pounds are referred to using their symbols of `€` and `£`
+respectively.
+
+#### Borders
+
+`numbers-parser` supports reading and writing cell borders, though the
+interface for each differs. Individual cells can have each of their four
+borders tested, but when drawing new borders, these are set for the
+table to allow for drawing borders across multiple cells. Setting the
+border of merged cells is not possible unless the edge of the cells is
+at the end of the merged region.
+
+Borders are represented using the
+[Border](https://masaccio.github.io/numbers-parser/#numbers_parser.Border)
+class that can be initialized with line width, color and line style. The
+current state of a cell border is read using the
+[Cell.border](https://masaccio.github.io/numbers-parser/#numbers_parser.Cell.border)
+property. The
+[Table.set_cell_border](https://masaccio.github.io/numbers-parser/#numbers_parser.Table.set_cell_border)
+sets the border for a cell edge or a range of cells.
+
+## API
+
+For more examples and details of all available classes and methods,
+see the [full API docs](https://masaccio.github.io/numbers-parser/).
+
+## Command-line scripts
+
+When installed from [PyPI](https://pypi.org/project/numbers-parser/),
+a command-like script `cat-numbers` is installed in Python’s scripts
+folder. This script dumps Numbers spreadsheets into Excel-compatible CSV
+format, iterating through all the spreadsheets passed on the
+command-line.
+
+```text
+usage: cat-numbers [-h] [-T | -S | -b] [-V] [--debug] [--formulas]
+                   [--formatting] [-s SHEET] [-t TABLE] [document ...]
+
+Export data from Apple Numbers spreadsheet tables
+
+positional arguments:
+  document                 Document(s) to export
+
+optional arguments:
+  -h, --help               show this help message and exit
+  -T, --list-tables        List the names of tables and exit
+  -S, --list-sheets        List the names of sheets and exit
+  -b, --brief              Don't prefix data rows with name of sheet/table (default: false)
+  -V, --version
+  --debug                  Enable debug output
+  --formulas               Dump formulas instead of formula results
+  --formatting             Dump formatted cells (durations) as they appear in Numbers
+  -s SHEET, --sheet SHEET  Names of sheet(s) to include in export
+  -t TABLE, --table TABLE  Names of table(s) to include in export
+```
+
+Note: `--formatting` will return different capitalization for 12-hour
+times due to differences between Numbers’ representation of these dates
+and `datetime.strftime`. Numbers in English locales displays 12-hour
+times with ‘am’ and ‘pm’, but `datetime.strftime` on macOS at least
+cannot return lower-case versions of AM/PM.
+
+## Limitations
+
+Current known limitations of `numbers-parser` are:
+
+- Formulas cannot be written to a document
+- Table styles that allow new tables to adopt a style across the whole
+  table are not planned.
+- Creating cells of type `BulletedTextCell` is not supported
+- New tables are inserted with a fixed offset below the last table in a
+  worksheet which does not take into account title or caption size
+- New sheets insert tables with formats copied from the first table in
+  the previous sheet rather than default table formats
+- Creating custom cell formats and cell data formats is experimental
+  and not all formats are supported. See
+  [Table.set_cell_formatting](https://masaccio.github.io/numbers-parser/#numbers_parser.Table.set_cell_formatting)
+  for more details.
+- Due to a limitation in Python’s
+  [ZipFile](https://docs.python.org/3/library/zipfile.html), Python
+  versions older than 3.11 do not support image filenames with UTF-8
+  characters (see [issue
+  69](https://github.com/masaccio/numbers-parser/issues/69)).
+  [Cell.style.bg_image](https://masaccio.github.io/numbers-parser/#numbers_parser.Style)
+  returns `None` for such files and issues a `RuntimeWarning`.
+- Pivot tables are unsupported, but re-saving a document is believed to work. Saving a document with a pivot table issues a UnsupportedWarning.
+
+## License
+
+All code in this repository is licensed under the [MIT
+License](https://github.com/masaccio/numbers-parser/blob/master/LICENSE.rst)
+