rics.strings#

Utility functions that act on or produce strings.

Functions

`camel_to_snake`(s)	Naive `camelCase` or `PascalCase` to `snake_case` conversion.
`format_bytes`(n, *[, binary, long, decimals])	Format bytes as a string.
`format_perf_counter`(start, *[, end, full])	Format performance counter output.
`format_seconds`(t, *[, allow_negative, full])	Format performance counter output.
`snake_to_camel`(s, *[, lower])	Naive `snake_case` to `camelCase` conversion.
`str_as_bool`(s)	Convert a string s to a boolean value.

format_bytes(n: int, *, binary: bool = True, long: bool = False, decimals: int = 2) → str[source]#

Format bytes as a string.

Parameters:

n – Number of bytes. Must be positive.
binary – Output binary prefixes if True, use metric (SI) prefixes otherwise.
long – Output out full unit and prefix if True, use abbreviated versions otherwise.
decimals – Number of decimals to include. Ignored for when n < base.

Returns:

Formatted number of bytes.

Examples

Formatting on prefix bounds

The jump as made at base / 2, where base is one of 1024 and 1000 (when binary=False).

>>> format_bytes(512 * 1024)
'512.00 KiB'
>>> format_bytes(512 * 1024 + 1)
'0.50 MiB'

This rule does not apply when n <= base.

>>> format_bytes(1024, long=True)
1024 bytes
>>> format_bytes(1024 + 1)
'1.00 KiB'

Output flags

>>> format_bytes(20190511, binary=False, long=False)
'20.19 MB'
>>> format_bytes(20190511, binary=False, long=True)
'20.19 megabytes'
>>> format_bytes(20190511, binary=True, long=False)
'19.26 MiB'
>>> format_bytes(20190511, binary=True, long=True)
'19.26 mebibytes'

Large outputs

Metric and binary have different upper limits.

>>> format_bytes(21**21, binary=True)
'2416.44 YiB'
>>> format_bytes(21**21, binary=True, long=True)
'2416.44 yobibytes'
>>> format_bytes(21**21, binary=False)
'5.84 RB'
>>> format_bytes(21**21, binary=False, long=True)
'5.84 ronnabytes'

If you ever see output like this, please let me know so that I can brag that someone important is using my little library.

format_perf_counter(start: float, *, end: float | None = None, full: bool = False) → str[source]#

Format performance counter output.

This function formats performance counter output based on the time elapsed. This is a thin wrapper around the format_seconds() function.

Parameters:

start – Start time.
end – End time. Retrieved using time.perf_counter() if None.
full – If True, show all non-zero components above four hours.

Returns:

A formatted performance counter time.

Examples

Basic usage.

>>> import time
>>> start = time.perf_counter()
>>> time.sleep(1219.0)  
>>> format_perf_counter(start)  
'20m 19s'

With no end argument given, the current time is retrieved using time.perf_counter().

format_seconds(t: float, *, allow_negative: bool = False, full: bool = False) → str[source]#

Format performance counter output.

Parameters:

t – Time in seconds.
allow_negative – If True, format negative t with a leading minus sign.
full – If True, show all non-zero components above four hours.

Returns:

A formatted performance counter time.

Examples

Basic usage.

>>> format_seconds(0.0000154)
'15μs'
>>> format_seconds(0.154)
'154ms'
>>> format_seconds(31.39)
'31.4s'

Clock units are used for t > 60 seconds.

>>> format_seconds(59.99)
'60.0s'
>>> format_seconds(60.00)
'60.0s'
>>> format_seconds(60.01)
'1m'
>>> format_seconds(309623.49)
'3d 14h'

Large intervals is rounded by default. You may set full=True to show full output.

>>> format_seconds(309623.49)
'3d 14h'
>>> format_seconds(309633.51, full=True)
'3d 14h 0m 34s'

Raises:: ValueError – If t < 0 and allow_negative=False (the default).

camel_to_snake(s: str) → str[source]#

Naive camelCase or PascalCase to snake_case conversion.

Parameters:: s – A string to convert.
Returns:: A snake_case string.
Raises:: IndexError – If string is empty.

Examples

Converting camel case strings.

>>> camel_to_snake("ClassName")
'class_name'
>>> camel_to_snake("variableName")
'variable_name'

Proper snake_case strings will not be changed.

>>> camel_to_snake("already_snake_case")
'already_snake_case'

Notes

Passing SCREAMING_SNAKE_CASE strings is not supported.

snake_to_camel(s: str, *, lower: bool = True) → str[source]#

Naive snake_case to camelCase conversion.

Parameters:

s – A string to convert.
lower – If False, return PamelCase instead of camelCase.

Returns:

A camelCase string.

Raises:

IndexError – If string is empty.

Examples

Converting snake case strings.

>>> snake_to_camel("snake_case")
'snakeCase'

Passing SCREAMING_SNAKE_CASE strings is supported.

>>> snake_to_camel("SCREAMING_SNAKE_CASE")
'screamingSnakeCase'

Set lower=False to convert to PascalCase or UpperCamelCase.

>>> snake_to_camel("SCREAMING_SNAKE_CASE", lower=False)
'ScreamingSnakeCase'

Notes

Passing camelCase strings is not supported.

str_as_bool(s: str) → bool[source]#

Convert a string s to a boolean value.

The output is determined by the content of s, as per the mapping shown below.

Keys:

False: ('0', 'false', 'no', 'off', 'disable', 'disabled')
True: ('1', 'true', 'yes', 'on', 'enable', 'enabled')

Matching is case-insensitive.

Parameters:

s – A string.

Returns:

A bool value.

Raises:

TypeError – If s is not a string.
ValueError – If s cannot be converted to bool using the keys above.

Examples

Basic usage.

>>> str_as_bool("true"), str_as_bool("false")
(True, False)

The input is cleaned and normalized.

>>> str_as_bool(" TRUE"), str_as_bool("False")
(True, False)

Input strings are normalized using str.strip() and str.lower().

Notes

Using bool(<str>) is equivalent to len(<str>) == 0.