Merge branch 'main' into fix-353

.github/scripts/no_pandas.py

@@ -1,5 +1,5 @@
 # %%
-from ast import NodeVisitor, Import, ImportFrom, alias, parse
+from ast import NodeVisitor, Import, ImportFrom, parse
 from pathlib import Path
 from os import walk
 

.github/workflows/ci-docs.yaml

@@ -2,7 +2,7 @@ on:
   push:
     branches:
       - main
-      - 'docs-preview-**'
+      - "docs-preview-**"
   pull_request:
     branches:
       - main
@@ -21,6 +21,8 @@ jobs:
         run: |
           python -m pip install ".[all]"
       - uses: quarto-dev/quarto-actions/setup@v2
+        with:
+          tinytex: true
       - name: Build docs
         run: |
           make docs-build

.github/workflows/ci-tests.yaml

@@ -15,7 +15,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ["3.9", "3.10", "3.11", "3.12"]
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
       fail-fast: false
 
     steps:

.gitignore

@@ -107,10 +107,14 @@ docs/source/generated/
 docs/source/reference/
 
 # Playground Scripts and temporary outputs
+.DS_Store
 playground*.py
 playground*.qmd
 playground.html
 playground_files
 manual-testing.py
 manual-testing.ipynb
-.DS_Store
+latex_testing.qmd
+latex_testing.pdf
+latex_examples.qmd
+latex_examples.pdf

.pre-commit-config.yaml

@@ -1,13 +1,13 @@
-exclude: "(.*\\.svg)|(.*\\.qmd)|(.*\\.ambr)|(.*\\.csv)|(.*\\.txt)|(.*\\.json)"
+exclude: "(.*\\.svg)|(.*\\.qmd)|(.*\\.ambr)|(.*\\.csv)|(.*\\.txt)|(.*\\.json)|(.*\\.ipynb)"
 repos:
-  - repo: https://github.com/pycqa/flake8
-    rev: 6.0.0
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    # Ruff version.
+    rev: v0.8.0
     hooks:
-      - id: flake8
-        types:
-          - python
-        additional_dependencies:
-          - flake8-pyproject
+      # Run the linter.
+      - id: ruff
+      # Run the formatter.
+      - id: ruff-format
   - repo: https://github.com/pre-commit/pre-commit-hooks
     rev: v4.5.0
     hooks:
@@ -16,7 +16,3 @@ repos:
       - id: check-yaml
         args: ["--unsafe"]
       - id: check-added-large-files
-  - repo: https://github.com/psf/black
-    rev: 24.2.0
-    hooks:
-      - id: black

.vscode/settings.json

@@ -8,7 +8,12 @@
   },
   "editor.rulers": [100],
   "[python]": {
-    "editor.defaultFormatter": "ms-python.black-formatter"
+    "editor.formatOnSave": true,
+    "editor.defaultFormatter": "charliermarsh.ruff",
+    "editor.codeActionsOnSave": {
+      "source.fixAll": "explicit",
+      "source.organizeImports": "explicit"
+    },
   },
   "python.testing.pytestArgs": ["tests"],
   "python.testing.unittestEnabled": false,

CITATION.cff

@@ -0,0 +1,29 @@
+cff-version: 1.2.0
+message: 'If you wish to cite the "great-tables" package use:'
+type: software
+license: MIT
+title: "great-tables: Make awesome display tables using Python."
+version: 0.14.0
+abstract:
+  Build display tables from tabular data with an easy-to-use set of methods.
+  With its progressive approach, we can construct display tables with a cohesive set
+  of table parts. Table values can be formatted using any of the included formatting
+  functions. Cell styles can be precisely added through a location targeting system. The way
+  in which Great Tables handles things for you means that you don't often have to worry about
+  the fine details.
+authors:
+  - family-names: Iannone
+    given-names: Richard
+    email: [email protected]
+    orcid: https://orcid.org/0000-0003-3925-190X
+  - family-names: Michael
+    given-names: Chow
+    email: [email protected]
+repository: https://pypi.org/project/great-tables/
+repository-code: https://github.com/posit-dev/great-tables
+url: https://posit-dev.github.io/great-tables/
+contact:
+  - family-names: Iannone
+    given-names: Richard
+    email: [email protected]
+    orcid: https://orcid.org/0000-0003-3925-190X

CONTRIBUTING.md

@@ -0,0 +1,50 @@
+# Contributing Guidelines
+
+There are many ways to contribute to the ongoing development of the Great Tables package. Some contributions can be rather easy to do (e.g., fixing typos, improving documentation, filing issues for feature requests or problems, etc.) whereas other contributions can require more time and patience (like answering questions and submitting pull requests with code changes). Just know that that help provided in any capacity is very much appreciated. :)
+
+## Filing Issues
+
+If you believe you found a bug, minimal reproducible example (MRE) for your posting to the [Great Tables issue tracker](https://github.com/posit-dev/great-tables/issues). Try not to include anything unnecessary, just the minimal amount of code that constitutes the reproducible bug. For useful guidelines on how to create an MRE, take a look at [this guide on Stack Overflow](https://stackoverflow.com/help/minimal-reproducible-example). We will try to verify the bug by running the code in the provided MRE. The quality of the MRE will reduce the amount of back-and-forth communication in trying to understand how to execute the code on our systems.
+
+## Answering questions
+
+One way to help is by simply answering questions. It's amazing how a little conversation could lead to better insights on a problem. Don't quite know the answer? That's okay too. We're all in this together.
+
+Where might you answer user questions? Some of the forums for Q&A on Great Tables include the _Issues_ and _Discussion_ pages in the repo. Good etiquette is key during these interactions: be a good person to all who ask questions.
+
+### Making Pull Requests
+
+Should you consider making a pull request (PR), please file an issue first and explain the problem in some detail. If the PR is an enhancement, detail how the change would make things better for package users. Bugfix PRs also require some explanation about the bug and how the proposed fix will remove that bug. A great way to illustrate the bug is to include an MRE. While all this upfront work prior to preparing a PR can be time-consuming it opens a line of communication with the package authors and the community, perhaps leading to a better enhancement or more effective fixes!
+
+Once there is consensus that a PR based on the issue would be helpful, adhering to the following process will make things proceed more quickly:
+
+- Create a separate Git branch for each PR
+- Look at the build status badges before and after making changes; these badges are available in the package [README](https://github.com/posit-dev/great-tables)
+- The Great Tables package follows the [Style Guide for Python Code](https://peps.python.org/pep-0008/) so please adopt those guidelines in your submitted code as best as possible
+- Comment your code, particularly in those hard-to-understand areas
+- Add test cases that cover the changes made in the PR; having tests for any new codepaths will help guard against regressions
+
+### Setting Up Your Development Environment
+
+To set up your development environment, you can follow these steps:
+
+- Clone the posit-dev/great-tables repository
+- Create a virtual environment for the folder
+- Install the package in editable mode with `pip install -e .` from the root of the project folder
+- Install the development dependencies with `pip install .[dev]` (have a look at the `pyproject.toml` file for the list of development dependencies)
+
+Our documentation use `quartodoc` which in turn requires a local install of the Quarto CLI. To install Quarto, go to <https://quarto.org/docs/get-started/> to get the latest build for your platform.
+
+We also use `ruff` for linting and formatting (this is part of our development dependencies). If using VS Code as your editor, it may be useful to install the `Ruff` extension. This will make it so any commits will pass the `pre-commit` checks. You can verify that any changes pass all pre-commit checks by running `pre-commit run --all-files`.
+
+If you are planning to investigate or submit a PR concerning the generation of table images, you need to install additional dependencies (`selenium`and`Pillow`) and this can be done by using `pip install .[all]`.
+
+### Building the Documentation Locally
+
+Building the documentation can be done with `make docs-build` from the root of the project folder. Locally building the documentation site is useful when you want to see how your changes will look during iteration. The site will be built in the `docs/_site` folder.
+
+### Running Tests Locally
+
+The tests are located in the `tests` folder and we use `pytest` for running them. To run all of the tests, use `make test`. If you want to run a specific test file, you can use `pytest tests/test_file.py`.
+
+If you create new tests involving snapshots, please ensure that the resulting snapshots are relatively small. After adding snapshots, use `make test-update` (this runs `pytest --snapshot-update`). A subsequent use of `make test` should pass without any issues.

README.md

@@ -1,6 +1,6 @@
 <div align="center">
 
-<a href="https://posit-dev.github.io/great-tables/"><img src="./docs/assets/GT_logo.svg" width="350px"/></a>
+<a href="https://posit-dev.github.io/great-tables/"><img src="https://posit-dev.github.io/great-tables/assets/GT_logo.svg" width="350px"/></a>
 
 _Absolutely Delightful Table-making in Python_
 
@@ -9,7 +9,7 @@ _Absolutely Delightful Table-making in Python_
 [![PyPI Downloads](https://img.shields.io/pypi/dm/great-tables)](https://pypistats.org/packages/great-tables)
 [![License](https://img.shields.io/github/license/posit-dev/great-tables)](https://img.shields.io/github/license/posit-dev/great-tables)
 
-[![CI Build](https://github.com/posit-dev/great-tables/workflows/CI%20Tests/badge.svg?branch=main)](https://github.com/posit-dev/great-tables/actions?query=workflow%3A%22CI+Tests%22+branch%3Amain)
+[![CI Build](https://github.com/posit-dev/great-tables/actions/workflows/ci-tests.yaml/badge.svg)](https://github.com/posit-dev/great-tables/actions/workflows/ci-tests.yaml)
 [![Codecov branch](https://img.shields.io/codecov/c/github/posit-dev/great-tables/main.svg)](https://codecov.io/gh/posit-dev/great-tables)
 [![Repo Status](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active)
 [![Documentation](https://img.shields.io/badge/docs-project_website-blue.svg)](https://posit-dev.github.io/great-tables/)
@@ -23,10 +23,10 @@ _Absolutely Delightful Table-making in Python_
 With **Great Tables** anyone can make wonderful-looking tables in Python. The philosophy here is that we can construct a wide variety of useful tables by working with a cohesive set of table components. You can mix and match things like a _header_ and _footer_, attach a _stub_ (which contains row labels), arrange _spanner labels_ over top of the _column labels_, and much more. Not only that, but you can format the cell values in a variety of awesome ways.
 
 <div align="center">
-<img src="./docs/assets/the_components_of_a_table.svg" width="800px">
+<img src="https://posit-dev.github.io/great-tables/assets/the_components_of_a_table.svg" width="800px">
 </div>
 
-It all begins with **table data** in the form of a Pandas or Polars DataFrame. You then decide how to compose your output table with the elements and formatting you need for the task at hand. Finally, the table is rendered by printing it at the console, including it in an notebook environment, or rendering it inside a **Quarto** document.
+It all begins with **table data** in the form of a Pandas or Polars DataFrame. You then decide how to compose your output table with the elements and formatting you need for the task at hand. Finally, the table is rendered to HTML (the default option) or to an image file.
 
 The **Great Tables** package is designed to be both straightforward yet powerful. The emphasis is on simple methods for the everyday display table needs (but power when you need it). Here is a brief example of how to use **Great Tables** to create a table from the included `sp500` dataset:
 
@@ -53,13 +53,15 @@ sp500_mini = sp500[(sp500["date"] >= start_date) & (sp500["date"] <= end_date)]
 ```
 
 <div align="center">
-<img src="./docs/assets/gt_sp500_table.svg" width="800px">
+<img src="https://posit-dev.github.io/great-tables/assets/gt_sp500_table.svg" width="800px">
 </div>
 
+Typically we use Great Tables in an notebook environment or within a [**Quarto**](https://quarto.org) document. Tables won't print to the console, but using the [`show()` method](https://posit-dev.github.io/great-tables/reference/GT.show.html#great_tables.GT.show) on a table object while in the console will open the HTML table in your default browser.
+
 There are ten datasets provided by **Great Tables**: `countrypops`, `sza`, `gtcars`, `sp500`, `pizzaplace`, `exibble`, `towny`, `metro`, `constants`, and `illness`.
 
 <div align="center" style="padding-top:20px">
-<img src="./docs/assets/datasets.png" style="width:100%;">
+<img src="https://posit-dev.github.io/great-tables/assets/datasets.png" style="width:100%;">
 </div>
 
 All of this tabular data is great for experimenting with the functionality available inside **Great Tables** and we make extensive use of these datasets in our documentation.
@@ -78,7 +80,7 @@ Another fine venue for discussion is in our [_Discord server_](https://discord.c
 
 [![Discord Server](https://img.shields.io/badge/Discord-Chat%20with%20us-blue?style=social&logo=discord&logoColor=purple)](https://discord.com/invite/Ux7nrcXHVV)
 
-Finally, there is the [_X account_](https://twitter.com/gt_package). There you'll find tweets about **Great Tables** (including sneak previews about in-development features) and other table-generation packages.
+Finally, there is the [_X account_](https://twitter.com/gt_package). There you'll find posts about **Great Tables** (including sneak previews about in-development features) and other table-generation packages.
 
 [![X Follow](https://img.shields.io/twitter/follow/gt_package?style=social)](https://twitter.com/gt_package)
 
@@ -92,18 +94,44 @@ The **Great Tables** package can be installed from **PyPI** with:
 $ pip install great_tables
 ```
 
+You can also install [Great Tables from Conda-Forge](https://anaconda.org/conda-forge/great_tables) by using:
+
+```bash
+conda install conda-forge::great_tables
+```
+
 If you encounter a bug, have usage questions, or want to share ideas to make this package better, please feel free to file an [issue](https://github.com/posit-dev/great-tables/issues).
 
 ## Code of Conduct
 
 Please note that the **Great Tables** project is released with a [contributor code of conduct](https://www.contributor-covenant.org/version/2/1/code_of_conduct/).<br>By participating in this project you agree to abide by its terms.
 
+## Contributing to **Great Tables**
+
+There are many ways to contribute to the ongoing development of the **Great Tables** package. Some contributions can be simple (like fixing typos, improving documentation, filing issues for feature requests or problems, etc.) and others might take more time and care (like answering questions and submitting PRs with code changes). Just know that anything you can do to help would be very much appreciated!
+
+Please read over the [contributing guidelines](https://github.com/posit-dev/great-tables/blob/main/CONTRIBUTING.md) for information on how to get started.
+
 ## 📄 License
 
 **Great Tables** is licensed under the MIT license.
 
 © Posit Software, PBC.
 
+## Citation
+
+If you use **Great Tables** in your research/project/product, we would appreciate a citation to the package. You can cite the package using the following BibTeX entry:
+
+```bibtex
+@software{Iannone_great_tables,
+author = {Iannone, Richard and Chow, Michael},
+license = {MIT},
+title = {{great-tables: Make awesome display tables using Python.}},
+url = {https://github.com/posit-dev/great-tables},
+version = {0.14.0}
+}
+```
+
 ## 🏛️ Governance
 
 This project is primarily maintained by [Rich Iannone](https://twitter.com/riannone) and [Michael Chow](https://twitter.com/chowthedog).