Sphinx CSV tools extension
Project description
A Sphinx plugin that extends the csv-table reStructuredText directive to add various features.
This is an adapted and probably enhanced version of the original sphinx-csv-filter which can be found here: sphinx-csv-filter
Prerequisites
You need to be using Sphinx and reStructuredText.
Installation
Install the package by running:
pip3 install sphinx-csv-tools
Set Up
To include the extension, add this line to config.py in your Sphinx project:
extensions = ['sphinx_csv_tools']
If you’re using other extensions, edit the existing list, or add this:
extensions.append('sphinx_csv_tools')
Use
This plugin adds the following options to the csv-table directive:
:include:
This option takes a Python dict specifying the column and a regular expression. Rows are included if the columnar value matches the supplied regular expression.
Originally from sphinx-csv-filter
Example
Only displays rows where the type-column is SRV or VM
.. csv-tools::
:header-rows: 1
:include: { 'Type': ['SRV', 'VM'] }
"Type","Name","Location","State","Internal_Remark"
"SRV","ESX01","RZ1","active","some bogus text"
"SRV","ESX02","RZ2","active","some bogus text"
"SRV","ESX03","RZ1","inactive","some bogus text"
"VM","DC01","RZ1","active","some bogus text"
"VM","DC02","RZ2","active","some bogus text"
"Switch","SW01","RZ1","active","some bogus text"
"Switch","SW02","RZ2","active","some bogus text"
"Bogus","SRV","RZ3","active","some bogus text"
:exclude:
This option takes a Python dict specifying the column and a regular expression. Rows are excluded if the columnar value matches the supplied regular expression.
Originally from sphinx-csv-filter
Example
Only displays rows where the State is not inactive
.. csv-tools::
:header-rows: 1
:exclude: { 'State': ['inactive'] }
"Type","Name","Location","State","Internal_Remark"
"SRV","ESX01","RZ1","active","some bogus text"
"SRV","ESX02","RZ2","active","some bogus text"
"SRV","ESX03","RZ1","inactive","some bogus text"
"VM","DC01","RZ1","active","some bogus text"
"VM","DC02","RZ2","active","some bogus text"
"Switch","SW01","RZ1","active","some bogus text"
"Switch","SW02","RZ2","active","some bogus text"
"Bogus","SRV","RZ3","active","some bogus text"
:included_cols:
This is a comma-separated list of columns to include in the output.
Originally from sphinx-csv-filter
Example
Only displays the columns Name, Type and State (in this specific order)
.. csv-tools::
:header-rows: 1
:included_cols: Name,Type,State
"Type","Name","Location","State","Internal_Remark"
"SRV","ESX01","RZ1","active","some bogus text"
"SRV","ESX02","RZ2","active","some bogus text"
"SRV","ESX03","RZ1","inactive","some bogus text"
"VM","DC01","RZ1","active","some bogus text"
"VM","DC02","RZ2","active","some bogus text"
"Switch","SW01","RZ1","active","some bogus text"
"Switch","SW02","RZ2","active","some bogus text"
"Bogus","SRV","RZ3","active","some bogus text"
:unique:
Takes a column and “uniques” the rows. Completely removes all table content and builds a new one with 2 columns:
The unique column
The count how often the row existed in the original table
Example
Will create a table with the columns Type and Count, listing each unique Type and the amount of times it was present in the table.
.. csv-tools::
:header-rows: 1
:unique: Type
"Type","Name","Location","State","Internal_Remark"
"SRV","ESX01","RZ1","active","some bogus text"
"SRV","ESX02","RZ2","active","some bogus text"
"SRV","ESX03","RZ1","inactive","some bogus text"
"VM","DC01","RZ1","active","some bogus text"
"VM","DC02","RZ2","active","some bogus text"
"Switch","SW01","RZ1","active","some bogus text"
"Switch","SW02","RZ2","active","some bogus text"
"Bogus","SRV","RZ3","active","some bogus text"
:summarize:
Creates a summary-row and summarizes given columns
Example
Creates a summary row summarizing the given port-columns. For mathematic functions to work properly the strings must be typecasted to float or int
.. csv-tools::
:header-rows: 1
:summarize: { 'Ports 1G': 'int', 'Ports 10G': 'float', 'Ports 100G': 'int' }
"Type","Name","Ports 1G","Ports 10G","Ports 100G"
"93180-YC-FX3","Leaf-1","0","48","6"
"93180-YC-FX3","Leaf-2","0","48","6"
"9348GC-FXP","Leaf-3","48","4","4"
"9348GC-FXP","Leaf-4","48","4","4"
:format:
Executes the format() function on all values of the given columns. The fromat-string can be defined in the options
Example
Formats the column RX with thousand-seperators and 0 precision. TX will also get the string “bps” appended.
.. csv-tools::
:header-rows: 1
:format: {"RX": "{:,.0f}", "TX": "{:,.0f} bps"}
"From","To","RX","TX"
"Host1","Host2",17394,545534435
"Host1","Host3",892374,34565656
"Host2","Host3",344565665,23434
:header-beautify:
Basically rewrites the header-line to new values. Prevents uncool things from happening when using the original :header: directive
Example
Rewrites the header to From Host,To Host,RX,TX
.. csv-tools::
:header-rows: 1
:header-beautify: From Host,To Host,RX,TX
"From","To","RX","TX"
"Host1","Host2",17394,545534435
"Host1","Host3",892374,34565656
"Host2","Host3",344565665,23434
:order:
Orders the rows by the values of a column in ascending (ASC/default) or descending (DESC) direction. The direction-parameter can be omitted
Example
Orders the rows by Location in descending order.
.. csv-tools::
:header-rows: 1
:order: Location,DESC
"Type","Name","Location","State","Internal_Remark"
"SRV","ESX02","RZ2","active","some bogus text"
"SRV","ESX01","RZ1","active","some bogus text"
"SRV","ESX03","RZ1","inactive","some bogus text"
"VM","DC01","RZ1","active","some bogus text"
"VM","DC02","RZ2","active","some bogus text"
"Switch","SW01","RZ3","active","some bogus text"
"Switch","SW02","RZ2","active","some bogus text"
"Bogus","SRV","RZ3","active","some bogus text"
Processing-order and combination
The options can be used in any combination. Be aware of the processing-order to understand the effects of combining different options
include
exclude
unique
summarize
format
included_cols
header_beautify
order
Using a header or not
Using a header with :header-rows: does enable you to specify the header-name in the options. If there is no header you have to specify the column index (starting with 0).
It is strongly advised to always use a header (to protect against columns shifting around) and only to use one header (:header-rows: 1)
Unforseen effects might occur when ore headers are used
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distributions
Built Distribution
Hashes for sphinx_csv_tools-0.1-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 2fa44865e5126bc4b8cc1f0a254b30a78b0477c56e20b7f21fde716b9f3b32e7 |
|
MD5 | a935650ec53006d563c55a40b66d0f46 |
|
BLAKE2b-256 | dcd3d50adad22b1cc910338d8904a34acf22f734aeef7dd367d81535f6d562ea |