faceted 0.2.1__tar.gz → 0.2.2__tar.gz

faceted-0.2.2/.codecov.yml

@@ -0,0 +1,14 @@
+# Configuration taken from xarray
+codecov:
+  require_ci_to_pass: yes
+
+coverage:
+  status:
+    project:
+      default:
+        # Require 1% coverage, i.e., always succeed
+        target: 1
+    patch: false
+    changes: false
+
+comment: off

faceted-0.2.2/.coveragerc

@@ -0,0 +1,2 @@
+[run]
+omit = faceted/tests/*, faceted/_version.py, versioneer.py

faceted-0.2.2/.github/workflows/pre-commit.yaml

@@ -0,0 +1,15 @@
+name: pre-commit
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  pre-commit:
+    name: "pre-commit hooks"
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v7
+    - uses: actions/setup-python@v6
+    - uses: pre-commit/action@v3.0.1

faceted-0.2.2/.github/workflows/tests.yml

@@ -0,0 +1,43 @@
+name: tests
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+env:
+  FORCE_COLOR: 1
+
+jobs:
+  pytest:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        python-version: ["3.13"]
+        os: [ubuntu-latest]
+        platform: [x64]
+
+    steps:
+    - uses: actions/checkout@v7
+
+    - uses: actions/setup-python@v6
+      with:
+        python-version: ${{ matrix.python-version }}
+  
+    - name: Install faceted
+      run: pip install -e ".[dev]"
+
+    - name: Environment information
+      run: python -m pip list
+
+    - name: Run tests
+      run: pytest -vv --cov=faceted --cov-report=xml
+
+    - name: Upload code coverage to Codecov
+      uses: codecov/codecov-action@v7
+      with:
+        file: ./coverage.xml
+        flags: unittests,${{ matrix.python-version }}
+        name: codecov-umbrella
+        fail_ci_if_error: false
+        token: ${{ secrets.CODECOV_TOKEN }}

faceted-0.2.2/.pre-commit-config.yaml

@@ -0,0 +1,9 @@
+repos:
+- repo: https://github.com/astral-sh/ruff-pre-commit
+  # Ruff version.
+  rev: v0.12.12
+  hooks:
+    # Run the linter.
+    - id: ruff-check
+    # Run the formatter.
+    - id: ruff-format

faceted-0.2.2/PKG-INFO

@@ -0,0 +1,122 @@
+Metadata-Version: 2.4
+Name: faceted
+Version: 0.2.2
+Summary: Figures with precise control over overall width, plot aspect ratio, between-plot spacing, and colorbar dimensions.
+Author-email: Spencer Clark <spencerkclark@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2018 Spencer Clark
+        
+        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: Documentation, https://faceted.readthedocs.io/en/latest/
+Project-URL: Repository, https://github.com/spencerkclark/faceted.git
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: matplotlib>=1.5
+Requires-Dist: numpy>=1.7
+Provides-Extra: dev
+Requires-Dist: cartopy; extra == "dev"
+Requires-Dist: coveralls; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: cartopy; extra == "docs"
+Requires-Dist: cftime; extra == "docs"
+Requires-Dist: ipython; extra == "docs"
+Requires-Dist: jupyter; extra == "docs"
+Requires-Dist: nc-time-axis; extra == "docs"
+Requires-Dist: netCDF4; extra == "docs"
+Requires-Dist: numpydoc; extra == "docs"
+Requires-Dist: pooch; extra == "docs"
+Requires-Dist: sphinx; extra == "docs"
+Requires-Dist: sphinx-gallery; extra == "docs"
+Requires-Dist: sphinx_rtd_theme; extra == "docs"
+Requires-Dist: xarray; extra == "docs"
+Dynamic: license-file
+
+faceted
+=======
+
+[![tests](https://github.com/spencerkclark/faceted/actions/workflows/tests.yml/badge.svg)](https://github.com/spencerkclark/faceted/actions/workflows/tests.yml) [![codecov](https://codecov.io/gh/spencerkclark/faceted/branch/master/graph/badge.svg?token=H1DBBSTQ2V)](https://codecov.io/gh/spencerkclark/faceted) [![Documentation
+Status](https://readthedocs.org/projects/faceted/badge/?version=latest)](https://faceted.readthedocs.io/en/latest/?badge=latest) [![PyPI](https://img.shields.io/pypi/v/faceted.svg)](https://pypi.python.org/pypi/faceted/)
+
+Figures with precise control over overall width, overall height,
+plot aspect ratio, between-plot spacing, and colorbar dimensions.
+
+Description
+-----------
+
+The purpose of this module is to make it easy to produce single-or-multi-panel
+figures in `matplotlib` with strict dimensional constraints.  For example,
+perhaps you would like to make a figure that fits exactly within a column of a
+manuscript *without any scaling*, and you would like the panels to be as large
+as possible, but retain a fixed aspect ratio (height divided by width).  Maybe
+some (or all) of your panels require an accompanying colorbar.  With
+out of the box `matplotlib` tools this is actually somewhat tricky.
+
+![readme-example.png](readme-example.png?raw=true)
+
+Internally, this module uses the flexible [`matplotlib` `AxesGrid` toolkit](https://matplotlib.org/2.0.2/mpl_toolkits/axes_grid/users/overview.html#axes-grid1),
+with some additional logic to enable making these kinds of
+dimensionally-constrained
+panel plots with precise padding and colorbar size(s).
+
+Another project with a similar motivation is [panel-plots](
+https://github.com/ajdawson/panel-plots); however it does not have support
+for adding colorbars to a dimensionally-constrained figure.  One part of the 
+implementation there that inspired part of what is done here is the ability 
+to add user-settable padding to the edges of the figure (to add space for 
+axes ticks, ticklabels, and labels).  This eliminates the need for using 
+`bbox_inches='tight'` when saving the figure, and enables you 
+to make sure that your figures are *exactly* the dimensions you need for your use.
+
+I intend to keep the scope of this project quite limited. I want the results it
+produces to remain extremely easy to understand and control.  For more
+complicated figure layouts, e.g. multiple panels with different sizes and
+aspect ratios, and a more magical approach to setting figure boundary padding
+and between-panel spacing, a library worth checking out is
+[proplot](https://github.com/lukelbd/proplot).  The ["smart tight layout" feature
+it provides](https://proplot.readthedocs.io/en/stable/why.html#id5) is an impressive 
+automated method of solving some of the same problems addressed by this library.
+
+For information on how to use `faceted`, see the documentation:
+https://faceted.readthedocs.io/en/latest/.
+
+Installation
+------------
+
+You can install `faceted` either from PyPI:
+```
+$ pip install faceted
+```
+or directly from source:
+```
+$ git clone https://github.com/spencerkclark/faceted.git
+$ cd faceted
+$ pip install -e .
+```

{faceted-0.2.1 → faceted-0.2.2}/README.md

@@ -1,9 +1,8 @@
 faceted
 =======
 
-[![Build
-Status](https://github.com/spencerkclark/faceted/workflows/tests/badge.svg?branch=master)](https://github.com/spencerkclark/faceted/actions) [![codecov](https://codecov.io/gh/spencerkclark/faceted/branch/master/graph/badge.svg?token=H1DBBSTQ2V)](https://codecov.io/gh/spencerkclark/faceted) [![Documentation
-Status](https://readthedocs.org/projects/faceted/badge/?version=latest)](https://faceted.readthedocs.io/en/latest/?badge=latest) [![PyPI](https://img.shields.io/pypi/v/faceted.svg)](https://pypi.python.org/pypi/faceted/) [![black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/python/black)
+[![tests](https://github.com/spencerkclark/faceted/actions/workflows/tests.yml/badge.svg)](https://github.com/spencerkclark/faceted/actions/workflows/tests.yml) [![codecov](https://codecov.io/gh/spencerkclark/faceted/branch/master/graph/badge.svg?token=H1DBBSTQ2V)](https://codecov.io/gh/spencerkclark/faceted) [![Documentation
+Status](https://readthedocs.org/projects/faceted/badge/?version=latest)](https://faceted.readthedocs.io/en/latest/?badge=latest) [![PyPI](https://img.shields.io/pypi/v/faceted.svg)](https://pypi.python.org/pypi/faceted/)
 
 Figures with precise control over overall width, overall height,
 plot aspect ratio, between-plot spacing, and colorbar dimensions.
@@ -39,11 +38,10 @@ I intend to keep the scope of this project quite limited. I want the results it
 produces to remain extremely easy to understand and control.  For more
 complicated figure layouts, e.g. multiple panels with different sizes and
 aspect ratios, and a more magical approach to setting figure boundary padding
-and between-panel spacing, a library potentially worth checking out is
-[proplot](https://github.com/lukelbd/proplot).  I have not tried it out
-personally; however, the "smart tight layout" feature it advertises sounds like
-a more automated attempt at solving some of the same problems addressed by this
-library.
+and between-panel spacing, a library worth checking out is
+[proplot](https://github.com/lukelbd/proplot).  The ["smart tight layout" feature
+it provides](https://proplot.readthedocs.io/en/stable/why.html#id5) is an impressive 
+automated method of solving some of the same problems addressed by this library.
 
 For information on how to use `faceted`, see the documentation:
 https://faceted.readthedocs.io/en/latest/.

faceted-0.2.2/docs/Makefile

@@ -0,0 +1,240 @@
+# Makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS      =
+SPHINXBUILD     = sphinx-build
+SPHINXATUOBUILD = sphinx-autobuild
+PAPER           =
+BUILDDIR        = _build
+
+# Internal variables.
+PAPEROPT_a4     = -D latex_paper_size=a4
+PAPEROPT_letter = -D latex_paper_size=letter
+ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+# the i18n builder cannot share the environment and doctrees with the others
+I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+
+.PHONY: help
+help:
+	@echo "Please use \`make <target>' where <target> is one of"
+	@echo "  html       to make standalone HTML files"
+	@echo "  livehtml   Make standalone HTML files and rebuild the documentation when a change is detected. Also includes a livereload enabled web server"
+	@echo "  dirhtml    to make HTML files named index.html in directories"
+	@echo "  singlehtml to make a single large HTML file"
+	@echo "  pickle     to make pickle files"
+	@echo "  json       to make JSON files"
+	@echo "  htmlhelp   to make HTML files and a HTML help project"
+	@echo "  qthelp     to make HTML files and a qthelp project"
+	@echo "  applehelp  to make an Apple Help Book"
+	@echo "  devhelp    to make HTML files and a Devhelp project"
+	@echo "  epub       to make an epub"
+	@echo "  epub3      to make an epub3"
+	@echo "  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
+	@echo "  latexpdf   to make LaTeX files and run them through pdflatex"
+	@echo "  latexpdfja to make LaTeX files and run them through platex/dvipdfmx"
+	@echo "  text       to make text files"
+	@echo "  man        to make manual pages"
+	@echo "  texinfo    to make Texinfo files"
+	@echo "  info       to make Texinfo files and run them through makeinfo"
+	@echo "  gettext    to make PO message catalogs"
+	@echo "  changes    to make an overview of all changed/added/deprecated items"
+	@echo "  xml        to make Docutils-native XML files"
+	@echo "  pseudoxml  to make pseudoxml-XML files for display purposes"
+	@echo "  linkcheck  to check all external links for integrity"
+	@echo "  doctest    to run all doctests embedded in the documentation (if enabled)"
+	@echo "  coverage   to run coverage check of the documentation (if enabled)"
+	@echo "  dummy      to check syntax errors of document sources"
+
+.PHONY: clean
+clean:
+	rm -rf $(BUILDDIR)/*
+	rm -rf generated/*
+	rm -rf auto_gallery/
+
+.PHONY: html
+html:
+	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+
+.PHONY: livehtml
+livehtml:
+	# @echo "$(SPHINXATUOBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html"
+	$(SPHINXATUOBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+
+.PHONY: dirhtml
+dirhtml:
+	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
+
+.PHONY: singlehtml
+singlehtml:
+	$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
+	@echo
+	@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
+
+.PHONY: html-noplot
+html-noplot:
+	$(SPHINXBUILD) -D plot_gallery=0 -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+
+.PHONY: pickle
+pickle:
+	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
+	@echo
+	@echo "Build finished; now you can process the pickle files."
+
+.PHONY: json
+json:
+	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
+	@echo
+	@echo "Build finished; now you can process the JSON files."
+
+.PHONY: htmlhelp
+htmlhelp:
+	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
+	@echo
+	@echo "Build finished; now you can run HTML Help Workshop with the" \
+	      ".hhp project file in $(BUILDDIR)/htmlhelp."
+
+.PHONY: qthelp
+qthelp:
+	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
+	@echo
+	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
+	      ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
+	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/faceted.qhcp"
+	@echo "To view the help file:"
+	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/faceted.qhc"
+
+.PHONY: applehelp
+applehelp:
+	$(SPHINXBUILD) -b applehelp $(ALLSPHINXOPTS) $(BUILDDIR)/applehelp
+	@echo
+	@echo "Build finished. The help book is in $(BUILDDIR)/applehelp."
+	@echo "N.B. You won't be able to view it unless you put it in" \
+	      "~/Library/Documentation/Help or install it in your application" \
+	      "bundle."
+
+.PHONY: devhelp
+devhelp:
+	$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
+	@echo
+	@echo "Build finished."
+	@echo "To view the help file:"
+	@echo "# mkdir -p $$HOME/.local/share/devhelp/faceted"
+	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/faceted"
+	@echo "# devhelp"
+
+.PHONY: epub
+epub:
+	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
+	@echo
+	@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
+
+.PHONY: epub3
+epub3:
+	$(SPHINXBUILD) -b epub3 $(ALLSPHINXOPTS) $(BUILDDIR)/epub3
+	@echo
+	@echo "Build finished. The epub3 file is in $(BUILDDIR)/epub3."
+
+.PHONY: latex
+latex:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo
+	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
+	@echo "Run \`make' in that directory to run these through (pdf)latex" \
+	      "(use \`make latexpdf' here to do that automatically)."
+
+.PHONY: latexpdf
+latexpdf:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo "Running LaTeX files through pdflatex..."
+	$(MAKE) -C $(BUILDDIR)/latex all-pdf
+	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+
+.PHONY: latexpdfja
+latexpdfja:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo "Running LaTeX files through platex and dvipdfmx..."
+	$(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
+	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+
+.PHONY: text
+text:
+	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
+	@echo
+	@echo "Build finished. The text files are in $(BUILDDIR)/text."
+
+.PHONY: man
+man:
+	$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
+	@echo
+	@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
+
+.PHONY: texinfo
+texinfo:
+	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+	@echo
+	@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
+	@echo "Run \`make' in that directory to run these through makeinfo" \
+	      "(use \`make info' here to do that automatically)."
+
+.PHONY: info
+info:
+	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+	@echo "Running Texinfo files through makeinfo..."
+	make -C $(BUILDDIR)/texinfo info
+	@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
+
+.PHONY: gettext
+gettext:
+	$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
+	@echo
+	@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
+
+.PHONY: changes
+changes:
+	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
+	@echo
+	@echo "The overview file is in $(BUILDDIR)/changes."
+
+.PHONY: linkcheck
+linkcheck:
+	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
+	@echo
+	@echo "Link check complete; look for any errors in the above output " \
+	      "or in $(BUILDDIR)/linkcheck/output.txt."
+
+.PHONY: doctest
+doctest:
+	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
+	@echo "Testing of doctests in the sources finished, look at the " \
+	      "results in $(BUILDDIR)/doctest/output.txt."
+
+.PHONY: coverage
+coverage:
+	$(SPHINXBUILD) -b coverage $(ALLSPHINXOPTS) $(BUILDDIR)/coverage
+	@echo "Testing of coverage in the sources finished, look at the " \
+	      "results in $(BUILDDIR)/coverage/python.txt."
+
+.PHONY: xml
+xml:
+	$(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml
+	@echo
+	@echo "Build finished. The XML files are in $(BUILDDIR)/xml."
+
+.PHONY: pseudoxml
+pseudoxml:
+	$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
+	@echo
+	@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."
+
+.PHONY: dummy
+dummy:
+	$(SPHINXBUILD) -b dummy $(ALLSPHINXOPTS) $(BUILDDIR)/dummy
+	@echo
+	@echo "Build finished. Dummy builder generates no files."

faceted-0.2.2/docs/api.rst

@@ -0,0 +1,17 @@
+.. currentmodule:: faceted
+
+#############
+API reference
+#############
+
+Here we provide a reference for faceted's limited API (currently it offers just
+one public function).
+
+Functions
+=========
+
+.. autosummary::
+   :toctree: generated/
+
+   faceted
+   faceted_ax