Skip to main content
Yanked

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

English | 简体中文

PyPI Python License: MPL 2.0

A creative plotting library that draws data as stockings pulled up over a pair of legs.

A grouped stockchart: two series over three months

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.
A grouped chart comparing planned and actual weekend hours
Grouped chart — black_sheer (welt) and white_sheer (lace)
A single-series chart with negative values, all legs upright
Single series with negative values — every leg stays upright (heart_white)
Seven legs wearing seven different stocking styles
A sweep of presets — 5 fabric types, 4 top edges
A mirror chart with positive and negative values
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

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)

Source distribution for stockchart 0.1.0
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)

Table of built distributions (wheels) for stockchart 0.1.0
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

A 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.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page