numbers-parser 4.7.1__py3-none-any.whl → 4.8.0__py3-none-any.whl

numbers_parser-4.8.0.dist-info/METADATA

@@ -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)
+

{numbers_parser-4.7.1.dist-info → numbers_parser-4.8.0.dist-info}/RECORD

@@ -1,18 +1,18 @@
-numbers_parser/__init__.py,sha256=0VZ4d30FZu4yiR_Dxj28WAJBHKX3zwiiZuV_ie6w_sY,1898
+numbers_parser/__init__.py,sha256=hyoQ4x-1E8yDBMR128kZhSDLCfrnjNdz4_dEpKlekk4,1950
 numbers_parser/_cat_numbers.py,sha256=-HboBJT11Vjcr8sjLZl7Z6qAapnPEc_kFYq6PTqON20,4619
 numbers_parser/_unpack_numbers.py,sha256=zfpBOfM92rMHSRQVR4tExf0fWI2Lbbb6WrwQPoq4gMo,5689
 numbers_parser/bullets.py,sha256=OnVVMPjhTDrC-ncw52Gb00UEXNmn2Rvd3xi7lfqW3hk,2616
-numbers_parser/cell.py,sha256=8WKFylYxMKGzscqHgIFHFoEkXCNWnhh4DKajm6gTAXg,26634
-numbers_parser/cell_storage.py,sha256=oKHjV9dYN-4r6E1t8Q8AF_gfc5HDYb0GfUbLTc0MDnI,33574
-numbers_parser/constants.py,sha256=lA4OWeso0jxawaNR3ulHNHV7ycJMWElBANEDrWe7V_E,2133
+numbers_parser/cell.py,sha256=aWQpVAAY-YmJW3ADU-cQGEmMDrPYCtaY02KNoKgB6ew,35399
+numbers_parser/cell_storage.py,sha256=_anyiHnG-pAZ9OTSdisT7lted9PGSzQcn_-xpsJVU0o,32873
+numbers_parser/constants.py,sha256=4D_u5v8r2YQGBK-ScRL6jGHhThFpxKpbS8LnTuVvlR4,7179
 numbers_parser/containers.py,sha256=b9sOCBd60YjMxJ-s9u-erWusA3guHU-c1RAUqM8CyKs,4191
 numbers_parser/currencies.py,sha256=8k4a3WKmDoHeurkDICymHX13N7ManHSTaka_JNXCZYA,3767
 numbers_parser/data/empty.numbers,sha256=8JOp035V-p2ff9_Wao7mLcYvb6_if6O2cus_esjVA9k,90316
-numbers_parser/document.py,sha256=2NJX6tAxKPOxV-4v-Py1Qdj40bu6ljtAsZk9vIRLzC4,21293
+numbers_parser/document.py,sha256=V3XiPKgk68Sp607ZLQfahEEO-PiKN2TH5AX_iCpJaxI,48087
 numbers_parser/exceptions.py,sha256=G8dASUQZI8ksHYRVfdGWJzgsJD5CBpcZvmDJUZTqT-c,670
 numbers_parser/experimental.py,sha256=WARjTa-2ePb8Ga8Q6oDP6EJCs12ofLRF2YpwzUu66ZI,374
 numbers_parser/file.py,sha256=ivcl5326TQXwj1GP9FCh-WiM_oXZumgQdByehAEw1f8,3966
-numbers_parser/formula.py,sha256=nTgK1RolKCWD-xvspKjWthKKdWXFYbULiMjljSkLDpc,10644
+numbers_parser/formula.py,sha256=JRsG0L21wS70oJ-FB46Amyoy-sKizWb-iUhSXUcVJ-U,10572
 numbers_parser/generated/TNArchives_pb2.py,sha256=txkTtPHvdXVvv7zO1dHCxxnixaFulK7hJVLQrH3cIJc,16007
 numbers_parser/generated/TNArchives_sos_pb2.py,sha256=AYI1X5t5Gb4l941jXlHEY0v97ToIze0bSYBR7KQmS0A,1215
 numbers_parser/generated/TNCommandArchives_pb2.py,sha256=AtDBJ_r-slDRVzHxJdXXZPAhpf-jpHj27ujIa2-aPtg,18271
@@ -50,11 +50,11 @@ numbers_parser/generated/fontmap.py,sha256=pqc1HwwTr3UbFMmhUaHJg1dX5-3pXbyhfS2bk
 numbers_parser/generated/functionmap.py,sha256=VdZo0ERMYONcrnJFwABcSCHb8pjA4wY2ogt8Janz57M,6082
 numbers_parser/iwafile.py,sha256=MuFIlB_hdXTTZflxoX_ZvA_68OaJkmRQ4eJ2UAiCKXQ,11833
 numbers_parser/mapping.py,sha256=in8W3S8DmTcPefFaxnATLw0FQ4YnFsnAE-cl5dljzJE,32215
-numbers_parser/model.py,sha256=d4gg_H7NRlCqnrrBxuxkYCji8tTPJtoZ3_PziOhSijM,91597
+numbers_parser/model.py,sha256=MY3qrLVIGwXX4xOQAlN0uN_njoisdiM5LQJJPPT7wPQ,98925
 numbers_parser/numbers_cache.py,sha256=1ghEBghQAYFpPiEeOtb74i016mXc039v1pOubbqvaLs,1141
 numbers_parser/numbers_uuid.py,sha256=-LeAj_ULC0va57pEmyegGY0xXqkNNjyuLukCaiQJhOk,2642
-numbers_parser-4.7.1.dist-info/LICENSE.rst,sha256=8vTa1-5KSdHrTpU9rlheO5005EWReEPMpjV7BjSaMc4,1050
-numbers_parser-4.7.1.dist-info/METADATA,sha256=qXUANus3bKmo23JzLCVrIGpsUmCajDoH5yicZgqZxig,33840
-numbers_parser-4.7.1.dist-info/WHEEL,sha256=7Z8_27uaHI_UZAc4Uox4PpBhQ9Y5_modZXWMxtUi4NU,88
-numbers_parser-4.7.1.dist-info/entry_points.txt,sha256=V91uB9vBPxf3eCY1h-0syv21imYCT0MJfMxf87DmwIk,115
-numbers_parser-4.7.1.dist-info/RECORD,,
+numbers_parser-4.8.0.dist-info/LICENSE.rst,sha256=8vTa1-5KSdHrTpU9rlheO5005EWReEPMpjV7BjSaMc4,1050
+numbers_parser-4.8.0.dist-info/METADATA,sha256=is-2Cwuuhq9It-c28uaOEfk089WxNutFQc95g2Nvf6E,16089
+numbers_parser-4.8.0.dist-info/WHEEL,sha256=FMvqSimYX_P7y0a7UY-_Mc83r5zkBZsCYPm7Lr0Bsq4,88
+numbers_parser-4.8.0.dist-info/entry_points.txt,sha256=V91uB9vBPxf3eCY1h-0syv21imYCT0MJfMxf87DmwIk,115
+numbers_parser-4.8.0.dist-info/RECORD,,

{numbers_parser-4.7.1.dist-info → numbers_parser-4.8.0.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: poetry-core 1.5.2
+Generator: poetry-core 1.8.1
 Root-Is-Purelib: true
 Tag: py3-none-any