This release has been yanked by its maintainers, and will be ignored by installers, except when explicitly specified.
Consider using release 0.2.0 instead.
Reason given by maintainers: LECENSE changed
Stock Chart
A creative plotting library that draws data as stockings pulled up over a pair of legs.
stockchart is a playful alternative to the bar chart. Each value becomes the height of a
stocking pulled up over a leg: a larger value means more stocking, and zero is a bare leg.
It is made for infographics, slides, posters, and anywhere a chart should be memorable
rather than conventional.
- Values → stocking height. Grouped, paired, and positive/negative mirror charts are supported.
- 19 built-in styles. Sheer, opaque tights, stripes, knit, fishnet, polka dots, hearts, lace trims, and more.
- Data-science friendly. Lists, NumPy arrays, dictionaries, and pandas
DataFrame/Series. pandas is optional and never imported by the library itself. - Native high-resolution output. Stocking textures and lighting are generated at the target pixel density, not upscaled from a bitmap.
- Composable by design. Start with one-line
bar(); drop down to pixel-level placement when you need a custom layout. - No matplotlib. Text and lines are rendered with Skia, including a per-character font fallback for Chinese, Japanese, and Korean.
|
Grouped chart — black_sheer (welt) and white_sheer (lace)
|
Single series with negative values — every leg stays upright ( heart_white)
|
|
A sweep of presets — 5 fabric types, 4 top edges |
Mirror chart — positive and negative values |
Installation
pip install stockchart
or with uv:
uv add stockchart
Requires Python 3.12 or newer. Runtime dependencies are skia-python, numpy, and
pillow.
Quick start
from stockchart import bar
bar(
[[320, 210], [450, 280], [510, 190]],
labels=["Jan", "Feb", "Mar"],
series_labels=["This site", "Neighbor"],
title="Monthly report",
xlabel="Month",
ylabel="Active users",
style=["black_sheer", "white_sheer"],
value_labels=True,
seed=2,
).save("chart.png")
The result is the image at the top of this README. bar() maps the data, chooses leg
assets, lays out groups, and draws the axes. It returns a BarPlot that can be saved
directly or adjusted further.
A mirror chart for positive and negative values:
from stockchart import mirror_bar
mirror_bar(
[4.2, -2.8, 6.1, -5.5, 3.4, -1.9],
labels=["Mon", "Tue", "Wed", "Thu", "Fri", "Sat"],
title="Daily change",
style="gray_sheer",
value_labels=True,
seed=2,
).save("mirror.png")
Data input
Pass the data structure you already have:
| Input | How it is interpreted |
|---|---|
| 1-D list / tuple / sequence | One series |
2-D sequence (groups, series) |
Grouped data |
numpy.ndarray |
1-D or 2-D arrays |
dict of scalars |
Keys become x-axis labels, one series |
dict of equal-length sequences |
Keys become series names and a legend is generated |
pandas DataFrame |
Index → x labels, columns → series names |
pandas Series |
Index → x labels, one series |
PlotData |
Already-normalized data |
For example, a DataFrame gets its labels and legend automatically:
import pandas as pd
from stockchart import bar
df = pd.DataFrame(
{"This site": [320, 450, 510], "Neighbor": [210, 280, 190]},
index=["Jan", "Feb", "Mar"],
)
bar(df, title="Monthly report", style=["black_sheer", "white_sheer"]).save("chart.png")
Explicit labels= and series_labels= override anything inferred from the data. Custom
containers can be registered with register_data_type; see the
data input reference.
Stocking styles
Pass a preset name, or a list of names to cycle through styles:
bar(
[5, 6, 7, 8, 6, 9, 4],
labels=["Sheer", "Lace", "Stripe", "Knit", "Fishnet", "Dots", "Tights"],
title="One of each",
style=[
"nude_sheer",
"white_sheer",
"stripe_rainbow",
"knit_cream",
"fishnet_black",
"polka_black",
"black_pantyhose",
],
value_labels=True,
seed=3,
)
The 19 presets cover sheer stockings, opaque tights, stripes, ribbed knit, fishnet,
polka dots, hearts, lace trims, and more. For direct control, pass a StockingStyle
built from Plain, Striped, Ribbed, Fishnet, or Dotted fabrics with a
Bare, Welt, Lace, or Fade top edge. The full style table is in the
rendering reference.
Titles, axis names, and options
bar(
data,
title="Monthly report", # centered over the plot by default
xlabel="Month",
ylabel="Active users",
title_align="left", # restore a left-aligned title
grid=True,
axis_style="handdrawn",
legend_loc="bottom",
)
Chart-level parameters stay in the signature; lower-level options such as grid,
axis_style, legend_loc, legend_ncol, x_label_rotation, bar_gap, and group_gap
are passed through a typed option bag. See the
ChartOptions table.
API layers
The library is deliberately layered, so you can choose how much control you want:
| Layer | What it gives you | Entry points |
|---|---|---|
| L0 assets | Leg metadata and built-in artwork | Leg, LegLibrary, load_leg |
| L1 primitives | One stocking, text, hand-drawn lines | render_stocking, StockingStyle, STYLES, draw_text, sketch_* |
| L2 free-form plot | Canvas, baseline, arbitrary leg placement | BarPlot, Scale, Canvas |
| L3 layout helpers | Uniform spacing and automatic leg selection | add_bars, add_grouped_bars, add_paired_bars |
| L4 one-liners | Data normalization and fully automatic layout | bar, mirror_bar |
For a more hands-on layout:
from stockchart import BarPlot, Scale
plot = BarPlot(1200)
plot.add_bars([300, 500, 400], style="black_sheer")
plot.add_x_labels(["A", "B", "C"])
plot.add_y_axis(Scale((0, 500), (0, 760)))
plot.add_title("Free-form layout")
plot.save("chart.png")
Output
BarPlot renders to PNG and can also return a PIL image or a NumPy array:
plot.save("chart.png", scale=2) # PNG at 2× pixel density
image = plot.to_pil()
array = plot.to_numpy()
scale controls output pixel density; stocking textures and lighting are regenerated at
that density. SVG and PDF output are intentionally not supported.
Documentation
- API reference — one page per layer
- Design notes
Development
git clone https://github.com/xie-huaaaan/stockchart.git
cd stockchart
uv sync
uv run python -m pytest
uv run ruff check . && uv run ruff format .
uv run python -m pyright
Issues and pull requests are welcome.
Status
0.1.x is an early public release. The rendering pipeline is stable, but the public API
may still change in minor releases.
License
Released under the Mozilla Public License 2.0 (MPL-2.0). You can use
stockchart in closed-source projects; if you modify MPL-covered source files, those
files must remain available under MPL-2.0.
Metadata
Release files for stockchart 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| stockchart-0.1.0.tar.gz | 6.1 MB | With provenance | Details for stockchart-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| stockchart-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for stockchart-0.1.0-py3-none-any.whl |
Total release size: 12.2 MB
Release files / stockchart-0.1.0.tar.gz
| Download URL | stockchart-0.1.0.tar.gz |
|---|---|
| Size | 6.1 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
af0bcd41b6e21b61d09bed1e326196dcd1226340e219bc01dd856f86cd4184f3
|
|
BLAKE2b-256 checksum How to use checksums |
263db211c137afedce91e1e6080e21f0b16e6d0c2b2cd10dcf5e04cd32f6e332
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 26, 2026.
Transparency logRelease files / stockchart-0.1.0-py3-none-any.whl
| Download URL | stockchart-0.1.0-py3-none-any.whl |
|---|---|
| Size | 6.1 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
889162a8ee99c46e4c3d04596d5978dca0f6841e2196d20a5683cc57fb103b14
|
|
BLAKE2b-256 checksum How to use checksums |
4ffbc2af1010c191347443f2a6eb547aeb960e7a1c8a0a76b998f3b167f91942
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 26, 2026.
Transparency logSecurity for stockchart 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for stockchart-0.1.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 26, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.