🎨 simplibs-extractor-css
A stylesheet project in one document — cleaned of its comments, or reduced to a list of what it styles.
The CSS add-on of simplibs-extractor. The extractor gathers the text files of a folder into one document and knows no language; this library teaches it
stylesheets — CSS, SCSS and Less: which files are worth reading, how to take comments and imports out of a source, how to write an outline of its selectors and at-rules, and five ready profiles that put it
together. A stylesheet is read by a small scanner that knows strings and url() addresses, never by a regex over the whole text — so a /* inside content: "/*" or a // inside an address is left alone.
pip install simplibs-extractor-css
simplibs-extractor css src-clean my_project
from simplibs.extractor_css import strip_css_comments, css_outline
strip_css_comments('a { content: "/* kept */"; /* gone */ }\n') # -> 'a { content: "/* kept */"; }\n'
css_outline("@media print { .a, .b { color: red; } }") # -> '@media print\n .a, .b\n'
pip installis the whole installation: the library announces itself to the extractor through an entry point, so the profiles show up insimplibs-extractor --list-profiles csswith nothing to import. The same steps are plain functions (str -> str) that you can use without the extractor at all.
🧭 The Core Philosophy
Cleaning a stylesheet with a few regular expressions works until the first file where it does not: a /* inside content: "/*", a // inside url(//cdn.example.com/a.png) (a comment in SCSS, an address everywhere
else), 0/**/auto that becomes the one broken value 0auto, an @import inside a comment. simplibs-extractor-css takes those traps seriously:
- A scanner, not a regex. One pass that knows strings,
url(...)addresses and comments, and jumps from one stop to the next. It is not a parser — it builds no tree — and it cannot fail: there is no syntax it refuses. - Plain CSS is not SCSS.
//is a comment only in.scssand.less. A step sees only the text, so the profile chooses the step by suffix, and a//in a plain.cssfile is never cut. - A comment is a border between two tokens.
0/**/autobecomes0 auto, not0auto: a space stays exactly where the two sides would merge, and nowhere else. A step cuts by position and changes nothing it did not find;strip_css_comments, run twice, returns the same text. - A damaged file is left as it is. A comment or a string that is never closed, braces that do not pair up: the text comes back unchanged, with a warning, and the extractor calls the file
partial. A step never cuts on a basis it does not trust. - Licences can stay. With
keep_license=Truethe comments that minifiers keep —/*! ... */,@license,@preserve— survive. Off by default: the default result has no comments at all. - Imports are one family.
@import,@useand@forwardall say "this file needs that one", so one step takes all three and there is no option for the difference. - The project's own is its own. The strict profile leaves out minified files, packages of other people and generated output — but
static/stays, because it is where a Django project keeps its own styles. - Functions first, actions on top. Every step is a plain function; the action is a thin wrapper of the same name, and the presets and profiles are built from the actions. The logic lives once.
- Layers that only look left.
constants←file_rules←logic←actions←presets←profiles←plugin— every layer imports only from those before it.
strip_css_comments("a { b: c; /* never closed\n") # -> 'a { b: c; /* never closed\n' unchanged, with a UserWarning: the comment is never closed
📦 Installation
pip install simplibs-extractor-css
Requires Python 3.11+. The package brings simplibs-extractor with it, and the command simplibs-extractor is available at once. Runtime dependencies (installed automatically):
simplibs-extractor (the profile, the registry, by_suffix),
simplibs-text (cutting the found ranges, the Span type, the whitespace presets),
simplibs-actions (the steps as actions),
simplibs-path and simplibs-rules (the file rules),
simplibs-validate (@validate_call on every public function) and
simplibs-types (int_positive, the depth of the outline).
🚀 Quick Start in 60 Seconds
Level 1: The command line
simplibs-extractor css src-clean my_project # the project's own stylesheets, cleaned -> my_project/css_src_clean.md
simplibs-extractor css outline my_project # selectors and at-rules only — the smallest overview
simplibs-extractor css code-no-imports my_project # the rules alone
simplibs-extractor css code-clean,data-all my_project # two profiles -> two files, one run
simplibs-extractor css data-all my_project --dry-run # plan and report, write nothing
simplibs-extractor --list-profiles css # the five profiles
Which one? data-all gives the files as they are, code-clean takes the comments away, src-clean does the same and leaves out minified files, other people's packages and generated output, code-no-imports takes also the
imports away, and outline keeps only what a project styles.
Level 2: The steps as functions
from simplibs.extractor_css import strip_css_comments, remove_css_imports, css_outline, css_comment_spans
strip_css_comments("a { margin: 0/**/auto; } /* n */\n") # -> 'a { margin: 0 auto; }\n'
strip_css_comments("// n\na { b: c; } // t\n", line_comments=True) # -> 'a { b: c; }\n' SCSS and Less
strip_css_comments("/*! v1 */\n/* x */\na { b: c; }\n", keep_license=True) # -> '/*! v1 */\na { b: c; }\n'
remove_css_imports('@import "a.css";\n@use "b";\na { c: d; }\n') # -> 'a { c: d; }\n'
css_outline("@media print { .a, .b { color: red; } }", max_depth=1) # -> '@media print\n'
css_comment_spans("a { b: c; } /* x */\n") # -> [(11, 19)]
Level 3: Actions and ready-made chains
from simplibs.extractor_css.actions import CssOutline, RemoveCssImports, StripCssComments
from simplibs.extractor_css.presets import CSS_LINE_CLEAN, CSS_PLAIN_NO_IMPORTS
steps = StripCssComments() >> RemoveCssImports()
steps('@import "a.css"; /* c */\na { b: c; }\n') # -> 'a { b: c; }\n'
CSS_PLAIN_NO_IMPORTS('@import "a.css";\n\n/* c */\na { b: c; }\n\n\nd { e: f; }\n') # -> 'a { b: c; }\nd { e: f; }\n'
CSS_LINE_CLEAN("// c\na { b: c; } // t\n") # -> 'a { b: c; }\n'
CssOutline(max_depth=1)("@media print { .a { b: c; } }\n") # -> '@media print\n'
Level 4: Your own profile from the parts
File rules combine with &, | and ~; the steps are presets; a registered profile is a name for both.
from simplibs.extractor import Profile, by_suffix, extract, register_profile
from simplibs.extractor_css.constants import CSS_LINE_COMMENT_SUFFIXES, CSS_PLAIN_SUFFIXES
from simplibs.extractor_css.file_rules import CSS_BASE, MINIFIED_NAME
from simplibs.extractor_css.presets import CSS_LINE_OUTLINE, CSS_PLAIN_OUTLINE
register_profile(Profile(
system="css", name="own-outline",
description="The outline of the stylesheets, minified files left out",
include=CSS_BASE,
exclude=MINIFIED_NAME,
steps={**by_suffix(CSS_PLAIN_OUTLINE, CSS_PLAIN_SUFFIXES), **by_suffix(CSS_LINE_OUTLINE, CSS_LINE_COMMENT_SUFFIXES)},
output_name="css_own_outline.md",
))
extract(source="my_project", profile="css/own-outline")
A changed copy of a profile of this library is one dataclasses.replace away:
from dataclasses import replace
from simplibs.extractor_css.profiles import CSS_SRC_CLEAN
mine = replace(CSS_SRC_CLEAN, name="mine", output_name="mine.md")
🛠️ Architecture & Package Structure
src/simplibs/extractor_css/
├── constants/ ◄── CSS_SUFFIXES, CSS_PLAIN_SUFFIXES, folder names, licence marks, the four patterns of the scanner
├── file_rules/ ◄── Rules on the path inside the source (domain folder)
│ ├── atomic/ ◄── DOT_NAME, MINIFIED_NAME, VCS_DIRS, DEPENDENCY_DIRS, OUTPUT_DIRS
│ └── css/ ◄── CSS_FILES, CSS_BASE, CSS_STRICT_EXCLUDE
├── logic/ ◄── The steps: plain functions that read a stylesheet with a scanner
│ ├── css_comment_spans.py strip_css_comments.py remove_css_imports.py css_outline.py
│ └── _helpers/ ◄── Private: the scanner (scan_css) and the small parts it is made of
├── actions/ ◄── The steps as Action classes (domain folder)
├── presets/ ◄── Ready-made chains: PLAIN and LINE of each (domain folder)
├── profiles/ ◄── The five Profile objects and CSS_PROFILES (domain folder)
├── plugin/ ◄── register_all: the target of the entry point
└── py.typed
The folder _helpers/ is private: it holds the scanner and the parts it is made of, and nothing in it is a public name.
The package root exports the steps and register_all. The four domain folders have their own __all__ and are imported through their domain — a function and an action are different kinds of thing and should stay
visibly different at the import line:
from simplibs.extractor_css import strip_css_comments, css_outline, register_all # the steps and the entry point
from simplibs.extractor_css.actions import StripCssComments # the steps as actions
from simplibs.extractor_css.file_rules import CSS_BASE, CSS_STRICT_EXCLUDE # the rules
from simplibs.extractor_css.presets import CSS_PLAIN_CLEAN # ready-made chains
from simplibs.extractor_css.profiles import CSS_SRC_CLEAN # the profiles as objects
The fixed values are imported from simplibs.extractor_css.constants. The ranges the steps find are simplibs.text.Span; the type is taken from simplibs-text, not defined here.
🔧 logic/ — The steps that read stylesheets
Plain functions: a stylesheet as a text in, a text out (one of them gives the positions of the comments). All take their options as keyword-only parameters. A file that looks damaged comes back unchanged, with a warning.
| Function | Description / Parameters |
|---|---|
css_comment_spans |
Finds the comments with the scanner; returns a Span for each, from the blanks in front to the end (text, keyword-only: line_comments=False, keep_license=False). |
strip_css_comments |
Removes the comments; a line that held only a comment disappears, a comment between two tokens leaves a space (text, keyword-only: line_comments=False, keep_license=False). |
remove_css_imports |
Removes @import, @use and @forward; the lines they stood on disappear (text, keyword-only: line_comments=False). |
css_outline |
Writes the headers of the blocks, one per line, indented by depth (text, keyword-only: line_comments=False, max_depth=None). |
⚙️ actions/ — Pipeline steps
Every step except css_comment_spans is also an Action of simplibs-actions: configured once, called with the text as its main input, chainable with >>. The options of the
function are the options of the action: StripCssComments(line_comments=True). Actions are a separate domain, imported through simplibs.extractor_css.actions; css_comment_spans has no action, because it returns spans and not a text.
| Action | Over | Description |
|---|---|---|
StripCssComments |
strip_css_comments |
Takes the comments out of the text flowing in. |
RemoveCssImports |
remove_css_imports |
Takes @import, @use and @forward out. |
CssOutline |
css_outline |
Turns the text into the list of its selectors and at-rules. |
➡️ README_EXTRACTOR_CSS_ACTIONS
🧩 presets/ — Ready-made chains
Chains of actions, built once, that the profiles use. Each exists twice: PLAIN for .css, where only /* ... */ is a comment, and LINE for .scss and .less, where // ... is one too.
| Preset | Chain |
|---|---|
CSS_PLAIN_CLEAN |
StripCssComments() >> CLEANUP_WHITESPACE — the imports stay. |
CSS_PLAIN_NO_IMPORTS |
StripCssComments() >> RemoveCssImports() >> COMPACT — the rules only. |
CSS_PLAIN_OUTLINE |
CssOutline() — the selectors and at-rules. |
CSS_LINE_CLEAN |
StripCssComments(line_comments=True) >> CLEANUP_WHITESPACE — the imports stay. |
CSS_LINE_NO_IMPORTS |
StripCssComments(line_comments=True) >> RemoveCssImports(line_comments=True) >> COMPACT |
CSS_LINE_OUTLINE |
CssOutline(line_comments=True) |
CLEANUP_WHITESPACE squeezes blank runs to one line, COMPACT removes every blank line.
➡️ README_EXTRACTOR_CSS_PRESETS
📋 profiles/ — The five profiles
Registered in the system css; also importable as Profile objects. A profile of a kind that has steps gives .css the PLAIN preset and .scss and .less the LINE one.
| Profile | Output | Description |
|---|---|---|
css/code-clean |
css_code_clean.md |
Stylesheets without comments and extra blank lines (imports stay). |
css/code-no-imports |
css_code_no_imports.md |
Pure rules: no imports, comments or blank lines. |
css/data-all |
css_data_all.md |
Every relevant stylesheet, as it is. |
css/outline |
css_outline.md |
Overview of the stylesheets: selectors and at-rules without declarations. |
css/src-clean |
css_src_clean.md |
Like code-clean, without minified files, packages of other people and generated output. |
CSS_PROFILES is the tuple of all five, in the order the listings show them.
➡️ README_EXTRACTOR_CSS_PROFILES
📐 file_rules/ — Which files are worth reading
Rules on the path inside the source folder: Rule objects of simplibs-rules, composable with &, | and ~.
| Rule | Description |
|---|---|
CSS_BASE |
The default choice: every stylesheet that is not hidden — minified files and SCSS partials included. |
CSS_FILES |
A file with a stylesheet suffix: .css, .scss, .less. |
CSS_STRICT_EXCLUDE |
What is not the project's own source: minified files, packages of other people, generated output, version control. |
DOT_NAME |
The file name starts with a dot. |
MINIFIED_NAME |
The name is something.min plus a suffix (app.min.css). |
VCS_DIRS |
A folder above the file is a version-control folder (.git, .svn, .hg, .bzr). |
DEPENDENCY_DIRS |
A folder above the file holds stylesheets of other people (node_modules, bower_components, vendor). |
OUTPUT_DIRS |
A folder above the file holds generated files (dist, staticfiles, coverage, …). |
➡️ README_EXTRACTOR_CSS_FILE_RULES
🔖 constants/ — Fixed values
Thirteen fixed values the rules, the scanner and the profiles are built from. The indented Sass syntax (.sass) is not among the suffixes: it has no braces, so its outline could not be read the same way.
| Constant | Description |
|---|---|
CSS_SUFFIXES |
(".css", ".scss", ".less") — every stylesheet the library reads. |
CSS_PLAIN_SUFFIXES |
(".css",) — where only /* ... */ is a comment. |
CSS_LINE_COMMENT_SUFFIXES |
(".scss", ".less") — where // ... is a comment too. |
CSS_EXTRA_LANGUAGE_BY_SUFFIX |
The code-fence language of .scss and .less. |
CSS_DEPENDENCY_DIR_NAMES |
Folders of stylesheets written by other people. |
CSS_OUTPUT_DIR_NAMES |
Folders of generated files and reports. |
CSS_LICENSE_START |
"/*!" — how a comment that has to survive minification begins. |
CSS_LICENSE_TAGS |
("@license", "@preserve") — words that mark a comment as one to keep. |
CSS_MINIFIED_ENDING |
".min" — what the stem of a minified stylesheet ends with. |
CSS_TOKEN_PATTERN |
Where the scanner stops in plain CSS: a quote, /*, url(. |
CSS_LINE_TOKEN_PATTERN |
Where the scanner stops in SCSS and Less: the same, and //. |
CSS_BLOCK_MARKS_PATTERN |
The braces and the semicolon that structure a stylesheet. |
CSS_IMPORT_PATTERN |
The start of @import, @use and @forward at the beginning of a line. |
➡️ README_EXTRACTOR_CSS_CONSTANTS
🔌 plugin/ — The meeting point with the extractor
| Function | Description / Parameters |
|---|---|
register_all |
Registers the languages of .scss and .less and the five profiles in the extractor's registries and returns the profile keys; the target of the entry point simplibs.extractor.plugins (keyword-only: replace_existing=True). |
The entry point lives in this library's pyproject.toml; the extractor's load_plugins() finds it, so nothing is imported by name. From Python, call load_plugins() of the extractor once before a profile is looked up.
➡️ README_EXTRACTOR_CSS_PLUGIN
⚠️ Exceptions
The library defines no exceptions of its own, and a stylesheet is never the cause of an error: a file that looks damaged is a warning, not an exception. What can be raised is a structured
simplibs.exception card from a library it builds on, or a ValidationError for a wrong argument; a caller that wants "any error of the family" catches SimpleError.
What is an exception and what is not:
| Situation | How it is reported |
|---|---|
| A step called directly on a stylesheet with a comment, a string or an address never closed | a UserWarning; the text comes back unchanged (css_comment_spans: []) |
css_outline on a stylesheet whose braces do not pair up |
a UserWarning; the text comes back unchanged |
| The same inside an extraction | not raised: the file stays in the output, marked partial, the warning is in the report |
A wrong type or value of an argument (text=5, max_depth=0) |
a ValidationError from simplibs-validate |
A profile key that is taken, with register_all(replace_existing=False) |
the card of the extractor's registry (EXTRACTOR_PROFILE_EXISTS) |
Each helper README ends with the errors of its own package.
📚 Documentation
The detailed references — every function, rule and profile with its parameters, return value, raised errors, an example and a look under the hood:
| Reference | What it describes |
|---|---|
| LOGIC | the four steps: comments, imports, the outline — and the scanner under them |
| ACTIONS | the steps as pipeline actions |
| PRESETS | the six ready-made chains, PLAIN and LINE |
| PROFILES | the five profiles, one stylesheet through each, a profile of your own |
| FILE_RULES | which files are worth reading: the atomic pieces and the rules of a stylesheet project |
| CONSTANTS | the fixed values: suffixes, folder names, licence marks, the patterns of the scanner |
| PLUGIN | register_all and how the extractor finds this add-on |
🔗 Related libraries
simplibs-extractor— the extractor this library is an add-on of: the six phases, the profiles and the command.simplibs-extractor-pythonandsimplibs-extractor-javascript— the sister add-ons for Python and for JavaScript and TypeScript projects.simplibs-text—remove_spanscuts the ranges the steps find,Spanis their type;CLEANUP_WHITESPACEandCOMPACTclose the presets.simplibs-actions— theActionthe steps are wrapped in.simplibs-path— the path rules (HasSuffix,NameIs,StemIs,AnyParentNameIs) andIGNORE_VCS.simplibs-rules— theRuleobject and its building blocks (IsIn,StartsWith,EndsWith).simplibs-validateandsimplibs-types— the check of every signature, and theint_positivetype of the outline depth.simplibs-exception— the error cards raised by the libraries underneath; it comes with the extractor.
☯️ About simplibs
All libraries in the simplibs (Simple Libraries) ecosystem share a common engineering philosophy:
- Dyslexia-friendly: We actively minimize cognitive load. Code is atomized into small, self-contained units, files are named directly after the logical task they perform, and explanations describe why something is designed, not just what it is.
- Programmer's Zen: Nothing should be missing, and nothing should be superfluous. We value clean execution paths and robust, understandable code architectures over rushed, messy feature sets.
- Defensive Style: We actively anticipate edge cases and failure modes so that only safe operational paths remain. Our code is built to degrade gracefully rather than crash unexpectedly.
- Minimalism: Find the most direct path to the goal in as few operational steps as possible without taking shortcuts on safety, readability, or completeness.
- Code as Craft: Code should be pleasant to look at, readable at a glance, and evoke structural harmony. We treat software engineering as a precision trade.
🤝 Contributing & Community
This is an open-source project built with love and care. We strongly believe in community collaboration and welcome any feedback, bug reports, or feature ideas!
- Want to contribute? Feel free to open an Issue or submit a Pull Request.
- Want to get in touch? If you'd like to discuss the project further, collaborate, or just say hello, feel free to open a GitHub Issue or start a Discussion.
📝 License
This library is released under the MIT License. Build great things!
Metadata
Release files for simplibs-extractor-css 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 |
|---|---|---|---|---|
| simplibs_extractor_css-0.1.0.tar.gz | 53.3 kB | Without provenance | Details for simplibs_extractor_css-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| simplibs_extractor_css-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for simplibs_extractor_css-0.1.0-py3-none-any.whl |
Total release size: 122.8 kB
Release files / simplibs_extractor_css-0.1.0.tar.gz
| Download URL | simplibs_extractor_css-0.1.0.tar.gz |
|---|---|
| Size | 53.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
1145949207af2ef91f666b82cde62652a7050d86bef131722e971cd759fddda2
|
|
BLAKE2b-256 checksum How to use checksums |
a8655ff7c401c5b1746501c59626f2722c0d6bf72ffc8ed50a707a6d1003c311
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.11.9
|
Release files / simplibs_extractor_css-0.1.0-py3-none-any.whl
| Download URL | simplibs_extractor_css-0.1.0-py3-none-any.whl |
|---|---|
| Size | 69.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
3af70a4774686e08f898896c3fc0107bcffa4edac82915a3aa80abb21cfeb7b1
|
|
BLAKE2b-256 checksum How to use checksums |
0aa5e9c1d7e1b87a038275e280fe4123e3722f333e7504b6d774cbb42cdc423f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.11.9
|
Security for simplibs-extractor-css 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.
No provenance found
None of the files in this release were uploaded with provenance metadata.
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.