From 42d557d48567851102725bf3f7bef39a0baecb72 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Nicol=C3=A1s=20Hatcher?= Date: Sat, 1 Feb 2025 17:10:42 +0100 Subject: [PATCH] UPDATE: Python docs --- bindings/python/docs/api_reference.rst | 210 +++++++++++++++++++++ bindings/python/docs/index.rst | 15 +- bindings/python/docs/installation.rst | 9 + bindings/python/docs/objects.rst | 32 ++++ bindings/python/docs/top_level_methods.rst | 6 + bindings/python/docs/usage_examples.rst | 37 ++++ webapp/app.ironcalc.com/frontend/deploy.sh | 5 + 7 files changed, 310 insertions(+), 4 deletions(-) create mode 100644 bindings/python/docs/api_reference.rst create mode 100644 bindings/python/docs/installation.rst create mode 100644 bindings/python/docs/objects.rst create mode 100644 bindings/python/docs/top_level_methods.rst create mode 100644 bindings/python/docs/usage_examples.rst create mode 100755 webapp/app.ironcalc.com/frontend/deploy.sh diff --git a/bindings/python/docs/api_reference.rst b/bindings/python/docs/api_reference.rst new file mode 100644 index 0000000..aefd32d --- /dev/null +++ b/bindings/python/docs/api_reference.rst @@ -0,0 +1,210 @@ + +API Reference +------------- + +In general methods in IronCalc use a 0-index base for the the sheet index and 1-index base for the row and column indexes. + + +.. method:: evaluate() + + Evaluates the model. This needs to be done after each change, otherwise the model might be on a broken state. + +.. method:: set_user_input(sheet: int, row: int, column: int, value: str) + + Sets an input in a cell, as would be done by a user typing into a spreadsheet cell. + + :param sheet: The sheet index (0-based). + :param row: The 1-based row index (first row is 1). + :param column: The 1-based column index (column “A” is 1). + :param value: The value to set, e.g. ``"123"`` or ``"=A1*2"``. + +.. method:: clear_cell_contents(sheet: int, row: int, column: int) + + Removes the content of the cell but leaves the style intact. + + :param sheet: The sheet index (0-based). + :param row: The 1-based row index (first row is 1). + :param column: The 1-based column index (column “A” is 1). + +.. method:: get_cell_content(sheet: int, row: int, column: int) -> str + + Returns the raw content of a cell. If the cell contains a formula, + the returned string starts with ``"="``. + + :param sheet: The sheet index (0-based). + :param row: The 1-based row index. + :param column: The 1-based column index. + :returns: The raw content, or an empty string if the cell is empty. + +.. method:: get_cell_type(sheet: int, row: int, column: int) -> PyCellType + + Returns the type of the cell (number, boolean, string, error, etc.). + + :param sheet: The sheet index (0-based). + :param row: The 1-based row index. + :param column: The 1-based column index. + :rtype: PyCellType + +.. method:: get_formatted_cell_value(sheet: int, row: int, column: int) -> str + + Returns the cell’s value as a formatted string, taking into + account any number/currency/date formatting. + + :param sheet: The sheet index (0-based). + :param row: The 1-based row index. + :param column: The 1-based column index. + :returns: Formatted string of the cell’s value. + +.. method:: set_cell_style(sheet: int, row: int, column: int, style: PyStyle) + + Sets the style of the cell at (sheet, row, column). + + :param sheet: The sheet index (0-based). + :param row: The 1-based row index. + :param column: The 1-based column index. + :param style: A PyStyle object specifying the style. + +.. method:: get_cell_style(sheet: int, row: int, column: int) -> PyStyle + + Retrieves the style of the specified cell. + + :param sheet: The sheet index (0-based). + :param row: The 1-based row index. + :param column: The 1-based column index. + :returns: A PyStyle object describing the cell’s style. + +.. method:: insert_rows(sheet: int, row: int, row_count: int) + + Inserts new rows. + + :param sheet: The sheet index (0-based). + :param row: The position before which new rows are inserted (1-based). + :param row_count: The number of rows to insert. + +.. method:: insert_columns(sheet: int, column: int, column_count: int) + + Inserts new columns. + + :param sheet: The sheet index (0-based). + :param column: The position before which new columns are inserted (1-based). + :param column_count: The number of columns to insert. + +.. method:: delete_rows(sheet: int, row: int, row_count: int) + + Deletes a range of rows. + + :param sheet: The sheet index (0-based). + :param row: The starting row to delete (1-based). + :param row_count: How many rows to delete. + +.. method:: delete_columns(sheet: int, column: int, column_count: int) + + Deletes a range of columns. + + :param sheet: The sheet index (0-based). + :param column: The starting column to delete (1-based). + :param column_count: How many columns to delete. + +.. method:: get_column_width(sheet: int, column: int) -> float + + Retrieves the width of a given column. + + :param sheet: The sheet index (0-based). + :param column: The 1-based column index. + :rtype: float + +.. method:: get_row_height(sheet: int, row: int) -> float + + Retrieves the height of a given row. + + :param sheet: The sheet index (0-based). + :param row: The 1-based row index. + :rtype: float + +.. method:: set_column_width(sheet: int, column: int, width: float) + + Sets the width of a given column. + + :param sheet: The sheet index (0-based). + :param column: The 1-based column index. + :param width: The desired width (float). + +.. method:: set_row_height(sheet: int, row: int, height: float) + + Sets the height of a given row. + + :param sheet: The sheet index (0-based). + :param row: The 1-based row index. + :param height: The desired height (float). + +.. method:: get_frozen_columns_count(sheet: int) -> int + + Returns the number of columns frozen (pinned) on the left side of the sheet. + + :param sheet: The sheet index (0-based). + :rtype: int + +.. method:: get_frozen_rows_count(sheet: int) -> int + + Returns the number of rows frozen (pinned) at the top of the sheet. + + :param sheet: The sheet index (0-based). + :rtype: int + +.. method:: set_frozen_columns_count(sheet: int, column_count: int) + + Sets how many columns are frozen (pinned) on the left. + + :param sheet: The sheet index (0-based). + :param column_count: The number of frozen columns (0-based). + +.. method:: set_frozen_rows_count(sheet: int, row_count: int) + + Sets how many rows are frozen (pinned) at the top. + + :param sheet: The sheet index (0-based). + :param row_count: The number of frozen rows (0-based). + +.. method:: get_worksheets_properties() -> List[PySheetProperty] + + Returns a list of :class:`PySheetProperty` describing each worksheet’s + name, visibility state, ID, and tab color. + + :rtype: list of PySheetProperty + +.. method:: set_sheet_color(sheet: int, color: str) + + Sets the tab color of a sheet. Use an empty string to clear the color. + + :param sheet: The sheet index (0-based). + :param color: A color in “#RRGGBB” format, or empty to remove color. + +.. method:: add_sheet(sheet_name: str) + + Creates a new sheet with the specified name. + + :param sheet_name: The name to give the new sheet. + +.. method:: new_sheet() + + Creates a new sheet with an auto-generated name. + +.. method:: delete_sheet(sheet: int) + + Deletes the sheet at the given index. + + :param sheet: The sheet index (0-based). + +.. method:: rename_sheet(sheet: int, new_name: str) + + Renames the sheet at the given index. + + :param sheet: The sheet index (0-based). + :param new_name: The new sheet name. + +.. method:: test_panic() + + A test method that deliberately panics in Rust. + Used for testing panic handling at the method level. + + :raises WorkbookError: (wrapped Rust panic) diff --git a/bindings/python/docs/index.rst b/bindings/python/docs/index.rst index 8d58208..8f62473 100644 --- a/bindings/python/docs/index.rst +++ b/bindings/python/docs/index.rst @@ -1,13 +1,20 @@ -IronCalc: The democratization of spreadsheets -============================================= +IronCalc +======== .. toctree:: :maxdepth: 2 :caption: Contents: -IronCalc is a spreadsheet engine that allows you to create, modify and safe spreadsheets. + installation + usage_examples + top_level_methods + api_reference + objects + +IronCalc is a spreadsheet engine that allows you to create, modify and save spreadsheets. A simple example that creates a model, sets a formula, evaluates it and gets the result back: .. literalinclude:: examples/simple.py - :language: python \ No newline at end of file + :language: python + diff --git a/bindings/python/docs/installation.rst b/bindings/python/docs/installation.rst new file mode 100644 index 0000000..1a3f4a4 --- /dev/null +++ b/bindings/python/docs/installation.rst @@ -0,0 +1,9 @@ +Installation +------------ + +You can simply do: + +.. code-block:: bash + + pip install ironcalc + diff --git a/bindings/python/docs/objects.rst b/bindings/python/docs/objects.rst new file mode 100644 index 0000000..a563149 --- /dev/null +++ b/bindings/python/docs/objects.rst @@ -0,0 +1,32 @@ +Objects +------- + +The following examples + + +``WorkbookError`` +^^^^^^^^^^^^^^^^^ +Exceptions of type ``WorkbookError`` are raised whenever there is a problem with +the workbook (e.g., invalid parameters, file I/O error, or even a Rust panic). +You can catch these exceptions in Python as follows: + +.. code-block:: python + + from ironcalc import WorkbookError + + try: + # Some operation on PyModel + pass + except WorkbookError as e: + print("Caught a workbook error:", e) + +``PyCellType`` +^^^^^^^^^^^^^^ +Represents the type of a cell (e.g., number, string, boolean, etc.). You can +check the type of a cell with :meth:`PyModel.get_cell_type`. + +``PyStyle`` +^^^^^^^^^^^ +Represents the style of a cell (font, bold, number formats, alignment, etc.). +You can get/set these styles with :meth:`PyModel.get_cell_style` +and :meth:`PyModel.set_cell_style`. \ No newline at end of file diff --git a/bindings/python/docs/top_level_methods.rst b/bindings/python/docs/top_level_methods.rst new file mode 100644 index 0000000..d5130eb --- /dev/null +++ b/bindings/python/docs/top_level_methods.rst @@ -0,0 +1,6 @@ +Top Level Methods +----------------- + +.. autofunction:: ironcalc.create +.. autofunction:: ironcalc.load_from_xlsx +.. autofunction:: ironcalc.load_from_icalc \ No newline at end of file diff --git a/bindings/python/docs/usage_examples.rst b/bindings/python/docs/usage_examples.rst new file mode 100644 index 0000000..9664fd8 --- /dev/null +++ b/bindings/python/docs/usage_examples.rst @@ -0,0 +1,37 @@ + +Usage Examples +-------------- + +Creating an Empty Model +^^^^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: python + + import ironcalc as ic + + model = ic.create("My Workbook", "en", "UTC") + +Loading from XLSX +^^^^^^^^^^^^^^^^^ + +.. code-block:: python + + import ironcalc as ic + + model = ic.load_from_xlsx("example.xlsx", "en", "UTC") + +Modifying and Saving +^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: python + + model = ic.create("model", "en", "UTC") + model.set_user_input(0, 1, 1, "123") + model.set_user_input(0, 1, 2, "=A1*2") + model.evaluate() + + # Save to XLSX + model.save_to_xlsx("updated.xlsx") + + # Or save to the binary format + model.save_to_icalc("my_workbook.icalc") diff --git a/webapp/app.ironcalc.com/frontend/deploy.sh b/webapp/app.ironcalc.com/frontend/deploy.sh new file mode 100755 index 0000000..7fc0773 --- /dev/null +++ b/webapp/app.ironcalc.com/frontend/deploy.sh @@ -0,0 +1,5 @@ +rm -rf dist/* +npm run build +cd dist/assets && brotli wasm* && brotli index-* +cd .. +scp -r * app.ironcalc.com:~/app/