Metadata-Version: 2.1
Name: jtf
Version: 1.1.14
Summary: Utilities for interacting with .jtf files.
Author: Timothy Phillips
License: MIT License
        
        Copyright (c) 2024 Tim Phillips
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/NotTimTam/jtf#readme
Project-URL: Repository, https://github.com/NotTimTam/jtf.py.git
Project-URL: Issues, https://github.com/NotTimTam/jtf/issues
Keywords: json,table,spreadsheet,fileformat,utility
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE

# jtf.py

Python utilities for interacting with .jtf files.

[View main repository.](https://github.com/NotTimTam/jtf)

[Read the syntax standard.](https://github.com/NotTimTam/jtf/blob/main/SYNTAX.md)

[View an example JTF file.](https://github.com/NotTimTam/jtf/blob/main/example.jtf)

This package is a direct conversion of the main JTF utilities. While the functions within this package use Python wording (like `list` instead of `array`), the casing required by the [JTF standard](https://github.com/NotTimTam/jtf/blob/main/SYNTAX.md) still applies when creating/parsing documents.

Requires Python 3.12 or newer.

# Installation

```terminal
pip install jtf
```

# Usage

```python
from jtf import JTF

document = JTF.parse("<document data>")
```

# Reference

## JTF Class

### Import

```python
from jtf import JTF
```

### `JTF.target_list_includes_cell(target, x, y)`

Checks if a target list targets a specific coordinate.

Parameters:

-   target (List<number|string>): The target list to check.
-   x (number|string): The x-coordinate to check.
-   y (number|string): The y-coordinate to check.

Returns `True` if the target list includes the specified coordinate, otherwise `False`.

### `JTF.parse(data)`

Parses JTF data into a readable object.

Parameters:

-   data (string|obj): The data to parse.

Returns an instance of the `Document` class based on the parsed data.

### `JTF.stringify(document)`

Convert a [`Document`](#document-class) object into a string.

-   document ([`Document`](#document-class)): The document to stringify.

Returns a string of the document's source data.

## Document Class

Generated by JTF class' [`parse`](#jtfparsedata) method.

### `Document.get_cell(table, x, y)`

Retrieves the content of a cell in a specified table.

Parameters:

-   table: The index of the table.
-   x: The x-coordinate of the cell.
-   y: The y-coordinate of the cell.

Returns the content of the cell, or `None` if the cell does not exist.

### `Document.to_csv()`

Converts each table in the document into CSV format.

Returns an object containing CSV strings for each table in the document.

### `Document.to_list()`

Converts each table in the document into lists.

Returns an object containing lists for each table in the document.

### `Document.stringify()`

Returns the data object represented by a JTF string.

### `Document.update_updated_at()`

Updates the document's `updatedAt` value to be the current timestamp.

### `Document.set_table(index, value)`

Set a table to a value. **Will overwrite existing tables.**

Parameters:

-   index (string|number): The index of the table.
-   data: The data to set.

### `Document.get_extra_processor_data(processor)`

Parameters:

-   processor (string): The unique identifier the data is stored under.

Returns a data object if found, or `None` if no object was found.

### `Document.set_extra_processor_data(processor, data, extend)`

Overwrites or updates data objects defined in a document's `metadata.extra` object.

Parameters:

-   processor (string): The unique identifier the data is stored under.
-   data (obj): An object of extra data to set.
-   extend (boolean): If `True`, destructures the new data object into existing data instead of overwriting it. (default `False`)

### `Document.tables`

An integer-string index of [`Table`](#table-class) objects.

### `Document.source`

The document's source object. This is the raw data that is parsed in `JTF.parse()`.

## Table Class

Generated by Document class and stored under `Document.tables` object.

### `Table.get_cell_styles(x, y)`

Retrieves the styles that must be applied to a cell.

Parameters:

-   x (string|number): The x-coordinate of the cell.
-   y (string|number): The y-coordinate of the cell.

Returns an object containing the classes and styles to apply to this cell.

### `Table.get_cell(x, y)`

Retrieves the content of a cell.

Parameters:

-   x (string|number): The x-coordinate of the cell.
-   y (string|number): The y-coordinate of the cell.

Returns the content of the cell, or `None` if the cell does not exist.

### `Table.set_cell(x, y, value)`

Set the content of a cell.

Parameters:

-   x (string|number): The x-coordinate of the cell.
-   y (string|number): The y-coordinate of the cell.
-   value (string|number|null|boolean): The value to set.

### `Table.to_csv()`

Converts the data object into CSV format.

Returns the table data in CSV format.

### `Table.to_list()`

Converts the table into a 2D list.

Returns the table as a 2D list.

### `Table.source`

The table's source object. This is the raw data that is stored under the table's document parent's `source.data`.

### `Table.label`

The table's label value. Can be used to set a `Table` instance's label. (`myTable.label = "myNewLabel"`)
