py-tailwind-utils 1.1.0

tailwind utility classes as first class python objects

py-tailwind-utils

A library that makes working with Tailwind CSS in python easier. It provides set of operators, functions, and python native objects that make it easier to express and manipulate tailwind directives.

Instead of styling a component of with a long string such "bg-pink-400 ring-offset-red-200 justify-content-start text-black-800", using this library you would instead write the same as first class python statement:

tstr(bg/pink/4, ring/offset/red/2, jc.start, fc/black/8)

This has several advantages:

• makes manipulation of styles such as
  -- passing style directives to functions,
  -- substitution of style through variable assignment a lot easier.
• makes it feasible to do bookkeeping and analyis of style used across various components of an webpage
• is basis for theme manipulation, i.e., bulk modify styles of several components using a single command.

A word of caution: This library does pollute the namespace of your python file/module, so be careful if using "from py_tailwind_utils import *". Also, not all construct of tailwind is available here.

Usage

Tailwind constructs as python objects

To begin with the library exports name that reflect various tailwind constructs. For, e.g. bg reflects tailwind utility class bg, bd reflects border and so on. See table for mapping between python constructs and tailwind constructs.

Tailwind expression builder

The above python-tailwind constructs support division operator using which one can create tailwind styling expression such as "bg-green-100", "ring-offset-red-200", etc. In py-tailwind-utils, these are expressed as first class python objects as bg/green/1 and ring/offset/red/2.

Tailwind utility as python enums

The library provides enum classes that encapsulate options for a tailwind utility. For e.g. for various options for justify content, the library provides enum class JustifyContent (or jc) as follows:

class JustifyContent(Enum):
    start = "justify-start"
    end = "justify-end"
    center = "justify-center"
    between = "justify-between"
    evenly = "justify-evenly"
    around = "justify-around"

The helps group directives or identify duplicates in a style definition.

Tailwind modifier functions

modifiers are expressed using functions over tailwind expression. For example,

hover(jc.end, bg/green/1, fc/blue/8)

*hover(*focus(bg/green/400), *focus(*placeholder(noop/fw.bold), fc/pink/100))

Convert python style expression to tailwind class expression

The tstr function converts python tailwind style expression to string value containing tailwind directives. In the example,

from py_tailwind_utils import tstr
tstr(bg/pink/4, ring/offset/red/2, jc.start, fc/pink/8)

tstr will convert to proper tailwind definition:

bg-pink-400 ring-offset-red-200 justify-start text-pink-800

Append/merge tailwind directive to an existing style list

Provides conc_twtags function to add/merge/append new directive to an exisiting list of styles. For e.g. if

mytags = [
        bg / green / 1,
        fc / blue / 1,
        flx.row,
    ]

is an exisiting set of styles, and if we add bg/blue/1 using conc_twtags, then it will perform a smart merge, i.e., it will override the exisiting directive that belong to the same utility class. So,

classes  = tstr(conc_twtags(*mytags, bg/blue/1))

will result in:

bg-blue-100 text-blue-100 flex-row

This feature of py-tailwind-tags comes in very useful for theme customization.

Remove a tailwind directive

Use remove_from_twtag_list to remove a tailwind directive from an existing list. An example:

mytags = [
        bg / green / 1,
        fc / blue / 1,
        jc.start, 
        flx.row,
    ]
 remove_from_twtag_list(mytags, jc.start)

Note: will throw ValueError if the request removeal object is not present in the list.

Store tailwind styles as Json

All the styles applied to a component can be exported out as json, organized by utility class. For example, to print out json use command:

res = tt.styClause.to_json(
    *hover(*focus(bg/green/400), *focus(*placeholder(noop/fw.bold), fc/pink/100)))
   

which will output: The res out:

{
    "passthrough": [],
    "bg": {
        "_val": "green-400",
        "_modifier_chain": ["hover", "focus"]
    },
    "FontWeight": {
        "_val": "bold",
        "_modifier_chain": ["hover", "focus", "placeholder"]
    },
    "fc": {
        "_val": "pink-100",
        "_modifier_chain": ["hover", "focus"]
    }
}

Load json back as tailwind style

Finally, once can read back the json, to convert the original tailwind style statement:

claus = tt.styClause.to_clause(res)
print(tstr(*claus))

Which outputs the original tailwind expression

hover:focus:bg-green-400 hover:focus:placeholder:font-bold hover:focus:text-pink-100

Not supported features

Background opacity modifiers are not yet supported

So, this expression will fail

All supported tailwind constructs in python as keywords or Enum classes

Reference

Style Tags

python keyword	tailwind construct
bd	border
from_	from
to_	to
via_	to
cc	None
container	container
inherit	inherit
current	current
transparent	transparent
first	first
full	full
screen	screen
hidden	hidden
last	last
none	none
scroll	scroll
span	span
text	text
visible	visible
auto	auto
group	group
double	double
clip	clip
invisible	invisible
absolute	absolute
grow	grow
bg	bg
x	x
y	y
duration	duration
inset	inset
max	max
min	min
offset	offset
opacity	opacity
order	order
ring	ring
row	row
rows	rows
col	col
cols	cols
space	space
stroke	stroke
gap	gap
end	end
fc	text
G	grid
H	h
lh	leading
mr	m
ovf	overflow
pd	p
ph	placeholder
resize	resize
sb	b
sl	l
sr	r
st	t
top	top
right	right
bottom	bottom
left	left
start	start
W	w
zo	z
noop
outline	outline
shadow	shadow

Style values

Tailwind Utility Class	Python enum class	python attr names	tailwind utility
DisplayBox	db
		b	block
		bi	inline-block
		i	inline
		f	flex
		fi	inline-flex
		t	table
		g	grid
BoxLayout	db
		b	block
		bi	inline-block
		i	inline
		f	flex
		fi	inline-flex
		t	table
		g	grid
WrapAround	wa
		r	float-right
		l	float-left
		n	float-none
ClearWrap	wc
		l	clear-left
		r	clear-right
		b	clear-both
		n	clear-none
ObjectFit	of
		cn	object-contain
		cv	object-cover
		f	object-fill
		n	object-none
		sd	object-scale-down
ObjectPosition	op
		b	object-bottom
		c	object-center
		l	object-left
		lb	object-left-bottom
		lt	object-left-top
		r	object-right
		rb	object-right-bottom
		t	object-top
Visibility	visibility
		v	visible
		nv	invisible
FlexLayout	flx
		row	flex-row
		rrow	flex-row-reverse
		col	flex-col
		rcol	flex-col-reverse
		wrap	flex-wrap
		rwrap	flex-wrap-reverse
		nowrap	flex-nowrap
		one	flex-1
		auto	flex-auto
		initial	flex-initial
		none	flex-none
		grow	flex-grow
		nogrow	flex-grow-0
		shrink	flex-shrink
		noshrink	flex-shrink-0
JustifyContent	jc
		start	justify-start
		end	justify-end
		center	justify-center
		between	justify-between
		evenly	justify-evenly
		around	justify-around
JustifyItems	ji
		start	justify-items-start
		end	justify-items-end
		center	justify-items-center
		stretch	justify-items-stretch
JustifySelf	js
		auto	justify-self-auto
		start	justify-self-start
		end	justify-self-end
		center	justify-self-center
		stretch	justify-self-stretch
AlignContent	ac
		start	content-start
		end	content-end
		center	content-center
		between	content-between
		evenly	content-evenly
		around	content-around
AlignItems	ai
		start	items-start
		end	items-end
		center	items-center
		stretch	items-stretch
		baseline	items-baseline
PlaceContent	pc
		start	place-content-start
		end	place-content-end
		center	place-content-center
		between	place-content-between
		evenly	place-content-evenly
		around	place-content-around
		stretch	place-content-stretch
PlaceItems	pi
		start	place-items-start
		end	place-items-end
		center	place-items-center
		stretch	place-items-stretch
PlaceSelf	ps
		auto	place-self-auto
		start	place-self-start
		end	place-self-end
		center	place-self-center
		stretch	place-self-stretch
FontFamily	ff
		sans	font-sans
		serif	font-serif
		mono	font-mono
FontSize	fz
		xs	text-xs
		sm	text-sm
		_	text-base
		lg	text-lg
		xl	text-xl
		xl2	text-2xl
		xl3	text-3xl
		xl4	text-4xl
		xl5	text-5xl
		xl6	text-6xl
FontWeight	fw
		thin	font-thin
		extralight	font-extralight
		light	font-light
		normal	font-normal
		medium	font-medium
		bold	font-bold
		extrabold	font-extrabold
		black	font-black
		semibold	font-semibold
LetterSpace	ls
		tighter	tracking-tighter
		tight	tracking-tight
		normal	tracking-normal
		wide	tracking-wide
		wider	tracking-wider
		widest	tracking-widest
LineHeight	lh
		none	leading-none
		tight	leading-tight
		snug	leading-snug
		normal	leading-normal
		relaxed	leading-relaxed
		loose	leading-loose
ListItems	li
		none	list-none
		disc	list-disc
		decimal	list-decimal
		inside	list-inside
		outside	list-outside
TextAlign	ta
		left	text-left
		center	text-center
		right	text-right
		justify	text-justify
		start	text-start
		end	text-end
TextTransform	tt
		u	uppercase
		l	lowercase
		c	capitalize
		n	normal-case
VerticalAlign	va
		top	align-top
		middle	align-middle
		bottom	align-bottom
BackgroundAttachment	ba
		f	bg-fixed
		l	bg-local
		s	bg-scroll
BorderRadius	bdr
		sm	rounded-sm
		md	rounded-md
		lg	rounded-lg
		full	rounded-full
		none	rounded-none
BorderStyle	bds
		solid	border-solid
		dashed	border-dashed
		dotted	border-dotted
		double	border-double
		none	border-none
		collapse	border-collapse
		separate	border-separate
Outline	outline
		none	outline-none
		_	outline
		dashed	outline-dashed
		dotted	outline-dotted
		double	outline-double
		hidden	outline-hidden
BoxShadow	shadow
		sm	shadow-sm
		_	shadow
		md	shadow-md
		lg	shadow-lg
		xl	shadow-xl
		xl2	shadow-2xl
		none	shadow-none
		inner	shadow-inner
Table	tbl
		auto	table-auto
		fixed	table-fixed
BoxTopo	bt
		bd	border
		container	container
PlacementPosition	ppos
		static	static
		fixed	fixed
		absolute	absolute
		relative	relative
		sticky	sticky
BoxSizing	boxsz
		b	box-border
		c	box-content
Prose	prse
		sm	prose-sm
		_	prose-base
		lg	prose-lg
		xl	prose-xl
		xl2	prose-2xl
GridFlow	gf
		row	grid-flow-row
		col	grid-flow-col
		rowd	grid-flow-row-dense
		cold	grid-flow-col-dense
GridAuto	ga
		cauto	grid-cols-auto
		cmin	grid-cols-min
		cmax	grid-cols-max
		cfr	grid-cols-fr
		rauto	grid-rows-auto
		rmin	grid-ros-min
		rmax	grid-rows-max
		rfr	grid-rows-fr

EndNotes

• Docs (in readthedocs format): https://github.com/Monallabs-org/py-tailwind-utils

• Developed By: webworks.monallabs.in