Functions¶

class prompty.functions.SpecialCharacters(container=None)¶

Functions to print special characters.

\unichar{code}

Generate a unicode character.

Parameters:	code – A unicode integer value. Can be prepended with `0x` or `0o` for hexadecimal or octal values.

\backslash: A backslash character (\).

\percent: A percent character (%).

\opencurly: An open curly brace character ({).

\closecurly: An close curly brace character (}).

\opensquare: An open square bracket character ([).

\closesquare: A close square bracket character (]).

\space: A single “space” character.

\newline: A new line character (\n).

\carriagereturn: A carriage return character (\r).

\escape: A bash escape code character (\033).

\tick: A tick symbol (✔).

\cross: A cross symbol (✘).

\highvoltage: A high voltage symbol (⚡).

class prompty.functions.PowerlineFunctions(container=None)¶

Functions for use with Powerline fonts.

You must have the powerline fonts package installed in order for these to render properly.

\powerline[bg='blue'][bg_next='default'][fg='white'][dir='right']{content}

Render content inside powerline arrows. It is possible to string together multiple powerlines together by ensuring that the next background colour is set match the next block’s background. For example:

\powerline[27][33]{this}  % colour 33 is carried over
\powerline[33][75]{is}    % colour 75 is carried over
\powerline[75]{cool}      % next colour is default bg colour

Parameters:	content – The contents of the powerline bg – Background colour, defaults to “blue” bg_next – Background colour of next block, defaults to “default” fg – Foreground colour, defaults to “white” dir – The arrow direction, defaults to “right”

\plbranch: A powerline branch symbol.

\plline: A powerline “line number” symbol.

\pllock: A powerline padlock symbol.

\plrightarrowfill: A powerline filled right arrow.

\plrightarrow: A powerline unfilled right arrow.

\plleftarrowfill: A powerline filled left arrow.

\plleftarrow: A powerline unfilled left arrow.

class prompty.functions.BashPromptEscapes(container=None)¶

Functions to mimic bash prompt escape sequences, similar to those defined here: https://www.tldp.org/HOWTO/Bash-Prompt-HOWTO/bash-prompt-escape-sequences.html

\date

The date in “Weekday Month Date” format (e.g., Tue May 26).

Equivalent to the bash prompt escape sequence \d

\datefmt[fmt='#X']

Generate the current date and time, and format it according to the given fmt string. Formats are given in the strptime() function documentation. However, because % is a special character in prompty, the control character is changed to #. For example: #a #b #d will render to “Weekday Month Date”.

If no fmt string is given, then the local time in 24hr format is returned.

Parameters:	fmt – format string, defaults to `#X` - Locale’s appropriate time representation, e.g.: `21:30:00`.

\user

The username of the current user.

Equivalent to the bash prompt escape sequence \u.

\hostname

The hostname up to the first ..

Equivalent to the bash prompt escape sequence \h.

\hostnamefull

The hostname.

Equivalent to the bash prompt escape sequence \H.

\workingdir

The current working directory.

Equivalent to the bash prompt escape sequence \w.

\workingdirbase

The basename of the current working directory.

Equivalent to the bash prompt escape sequence \W.

\dollar[euid]

If the effective UID is 0, a #, otherwise a $.

Equivalent to the bash prompt escape sequence \$.

Parameters:	euid – A user Id, defaults to the current user.

class prompty.functions.MiscFunctions(container=None)¶

\isrealpath[path]

If the current directory is a real path (i.e. not via a symbolic link) then return True, else return False.

Parameters:	path – A path, defaults to the current working path.
Return type:	bool

\exitsuccess

If the last command executed with a 0 status code, return True. Otherwise return False.

Return type:	bool

\equals{a}{b}

Return True if the two parameters a and b are equal (by value).

Return type:	bool

\max{a}{b}

Return the maximum of a and b.

Return type:	number

\min{a}{b}

Return the minimum of a and b.

Return type:	number

\gt{a}{b}

Return True if a > b.

Return type:	bool

\lt{a}{b}

Return True if a < b.

Return type:	bool

\gte{a}{b}

Return True if a >= b.

Return type:	bool

\lte{a}{b}

Return True if a <= b.

Return type:	bool

\ifexpr[thenval=''][elseval='']{cond}

If cond is equivalent to True, then return thenval, else return elseval.

Parameters:	cond (bool) – Condition thenval – Value returned if condition is equivalent to `True`, defaults to an empty string. elseval – Value returned if condition is equivalent to `False`, defaults to an empty string.

\lower{literal}: Return a lowercase representation of literal.

\upper{literal}: Return an uppercase representation of literal.

\join{args}

Join multiple strings together. The first argument is the delimiter, all subsequent arguments are strings to join.

Example:

\join{_}{joined}{with}{underscores}

Output:

joined_with_underscores

\justify[lpad=' '][rpad=' ']{left}{centre}{right}

Justify text in 3 columns to fill the terminal. Text in left will be left justified, text in centre will be centre justified, and text in right will be right justified. The padding characters between left and centre, and centre and right can be controlled with lpad and rpad, respectively.

Example:

\justify[_]{this is left}{in the centre}{on the right}

Output:

this is left________________________in the centre                        on the right

\right{literal}: Justify string literal right.

\smiley

Generate a smiley that has the following properties:

$:) - (colour green) Last command succeeded, user is not root
$:( - (colour red) Last command failed, user is not root
#:) - (colour green) Last command succeeded, user is root
#:( - (colour red) Last command failed, user is root

\randomcolour[seed]{literal}

Decorate literal with a random colour.

Parameters:	seed – The random hash seed, to enable consistency between calls.

\hashedcolour{literal}: Decorate literal with a colour based on its hash. This can be useful for generating a unique colour for different user or host names.

class prompty.vcs.VCSFunctions(container=None)¶

\isrepo

Return True if the current working directory is a version control repository.

Return type:	bool

\repobranch: The repository branch name.

\isrepodirty

Return True if the repository has uncommited modifications.

Return type:	bool

\ahead: Get the number of commits ahead of the remote repository.

\behind: Get the number of commits behind the remote repository.

\commit

\staged: Get the number of files that are currently staged.

\changed: Get the number of files that are modified and not staged.

\untracked: Get the number of untracked files that are in the repository (excluding those ignored).

\last_fetched: Get the time, in seconds, since the remote was last fetched.

\last_fetched_min: Get the time, in minutes, since the remote was last fetched.