Welcome to jaraco.text documentation!

For Enterprise

Professional support for jaraco.text is available as part of the Tidelift Subscription. Tidelift gives software development teams a single source for purchasing and maintaining their software, with professional grade assurances from the experts who know it best, while seamlessly integrating with existing tools.

Learn more Request a Demo

class jaraco.text.FoldedCase

Bases: str

A case insensitive string class; behaves just like str except compares equal when the only variation is case.

>>> s = FoldedCase('hello world')

>>> s == 'Hello World'
True

>>> 'Hello World' == s
True

>>> s != 'Hello World'
False

>>> s.index('O')
4

>>> s.split('O')
['hell', ' w', 'rld']

>>> sorted(map(FoldedCase, ['GAMMA', 'alpha', 'Beta']))
['alpha', 'Beta', 'GAMMA']

Sequence membership is straightforward.

>>> "Hello World" in [s]
True
>>> s in ["Hello World"]
True

Allows testing for set inclusion, but candidate and elements must both be folded.

>>> FoldedCase("Hello World") in {s}
True
>>> s in {FoldedCase("Hello World")}
True

String inclusion works as long as the FoldedCase object is on the right.

>>> "hello" in FoldedCase("Hello World")
True

But not if the FoldedCase object is on the left:

>>> FoldedCase('hello') in 'Hello World'
False

In that case, use in_:

>>> FoldedCase('hello').in_('Hello World')
True

>>> FoldedCase('hello') > FoldedCase('Hello')
False

>>> FoldedCase('ß') == FoldedCase('ss')
True
casefold(*args, **kwargs)

Return a version of the string suitable for caseless comparisons.

in_(other)

Does self appear in other?

index(sub)

Return the lowest index in S where substring sub is found, such that sub is contained within S[start:end].

Optional arguments start and end are interpreted as in slice notation. Raises ValueError when the substring is not found.

split(splitter=' ', maxsplit=0)

Return a list of the substrings in the string, using sep as the separator string.

sep

The separator used to split the string.

When set to None (the default value), will split on any whitespace character (including n r t f and spaces) and will discard empty strings from the result.

maxsplit

Maximum number of splits. -1 (the default value) means no limit.

Splitting starts at the front of the string and works to the end.

Note, str.split() is mainly useful for data that has been intentionally delimited. With natural text that includes punctuation, consider using the regular expression module.

class jaraco.text.SeparatedValues

Bases: str

A string separated by a separator. Overrides __iter__ for getting the values.

>>> list(SeparatedValues('a,b,c'))
['a', 'b', 'c']

Whitespace is stripped and empty values are discarded.

>>> list(SeparatedValues(' a,   b   , c,  '))
['a', 'b', 'c']
separator = ','
class jaraco.text.Splitter(*args)

Bases: object

object that will split a string with the given arguments for each call

>>> s = Splitter(',')
>>> s('hello, world, this is your, master calling')
['hello', ' world', ' this is your', ' master calling']
class jaraco.text.Stripper(prefix, lines)

Bases: object

Given a series of lines, find the common prefix and strip it from them.

>>> lines = [
...     'abcdefg\n',
...     'abc\n',
...     'abcde\n',
... ]
>>> res = Stripper.strip_prefix(lines)
>>> res.prefix
'abc'
>>> list(res.lines)
['defg\n', '\n', 'de\n']

If no prefix is common, nothing should be stripped.

>>> lines = [
...     'abcd\n',
...     '1234\n',
... ]
>>> res = Stripper.strip_prefix(lines)
>>> res.prefix = ''
>>> list(res.lines)
['abcd\n', '1234\n']
static common_prefix(s1, s2)

Return the common prefix of two lines.

classmethod strip_prefix(lines)
class jaraco.text.WordSet(iterable=(), /)

Bases: tuple

Given an identifier, return the words that identifier represents, whether in camel case, underscore-separated, etc.

>>> WordSet.parse("camelCase")
('camel', 'Case')

>>> WordSet.parse("under_sep")
('under', 'sep')

Acronyms should be retained

>>> WordSet.parse("firstSNL")
('first', 'SNL')

>>> WordSet.parse("you_and_I")
('you', 'and', 'I')

>>> WordSet.parse("A simple test")
('A', 'simple', 'test')

Multiple caps should not interfere with the first cap of another word.

>>> WordSet.parse("myABCClass")
('my', 'ABC', 'Class')

The result is a WordSet, providing access to other forms.

>>> WordSet.parse("myABCClass").underscore_separated()
'my_ABC_Class'

>>> WordSet.parse('a-command').camel_case()
'ACommand'

>>> WordSet.parse('someIdentifier').lowered().space_separated()
'some identifier'

Slices of the result should return another WordSet.

>>> WordSet.parse('taken-out-of-context')[1:].underscore_separated()
'out_of_context'

>>> WordSet.from_class_name(WordSet()).lowered().space_separated()
'word set'

>>> example = WordSet.parse('figured it out')
>>> example.headless_camel_case()
'figuredItOut'
>>> example.dash_separated()
'figured-it-out'
camel_case()
capitalized()
dash_separated()
classmethod from_class_name(subject)
headless_camel_case()
lowered()
classmethod parse(identifier)
space_separated()
trim(item)
>>> WordSet.parse('foo bar').trim('foo')
('bar',)
trim_left(item)

Remove the item from the beginning of the set.

>>> WordSet.parse('foo bar').trim_left('foo')
('bar',)
>>> WordSet.parse('foo bar').trim_left('bar')
('foo', 'bar')
>>> WordSet.parse('').trim_left('bar')
()
trim_right(item)

Remove the item from the end of the set.

>>> WordSet.parse('foo bar').trim_right('foo')
('foo', 'bar')
>>> WordSet.parse('foo bar').trim_right('bar')
('foo',)
>>> WordSet.parse('').trim_right('bar')
()
underscore_separated()
jaraco.text.clean(lines: Iterable[str])

Yield non-blank, non-comment elements from lines.

jaraco.text.drop_comment(line)

Drop comments.

>>> drop_comment('foo # bar')
'foo'

A hash without a space may be in a URL.

>>> drop_comment('http://example.com/foo#bar')
'http://example.com/foo#bar'
jaraco.text.indent(string, prefix=' ' * 4)
>>> indent('foo')
'    foo'
jaraco.text.is_binary(value)

Return True if the value appears to be binary (that is, it’s a byte string and isn’t decodable).

>>> is_binary(b'\xff')
True
>>> is_binary('\xff')
False
jaraco.text.is_decodable(value)

Return True if the supplied value is decodable (using the default encoding).

>>> is_decodable(b'\xff')
False
>>> is_decodable(b'\x32')
True
jaraco.text.join_continuation(lines)

Join lines continued by a trailing backslash.

>>> list(join_continuation(['foo \\', 'bar', 'baz']))
['foobar', 'baz']
>>> list(join_continuation(['foo \\', 'bar', 'baz']))
['foobar', 'baz']
>>> list(join_continuation(['foo \\', 'bar \\', 'baz']))
['foobarbaz']

Not sure why, but… The character preceding the backslash is also elided.

>>> list(join_continuation(['goo\\', 'dly']))
['godly']

A terrible idea, but… If no line is available to continue, suppress the lines.

>>> list(join_continuation(['foo', 'bar\\', 'baz\\']))
['foo']
jaraco.text.lines_from(input)

Generate lines from a importlib.resources.abc.Traversable path.

>>> lines = lines_from(files(__name__).joinpath('Lorem ipsum.txt'))
>>> next(lines)
'Lorem ipsum...'
>>> next(lines)
'Curabitur pretium...'
jaraco.text.multi_substitution(*substitutions)

Take a sequence of pairs specifying substitutions, and create a function that performs those substitutions.

>>> multi_substitution(('foo', 'bar'), ('bar', 'baz'))('foo')
'baz'
jaraco.text.normalize_newlines(text)

Replace alternate newlines with the canonical newline.

>>> normalize_newlines('Lorem Ipsum\u2029')
'Lorem Ipsum\n'
>>> normalize_newlines('Lorem Ipsum\r\n')
'Lorem Ipsum\n'
>>> normalize_newlines('Lorem Ipsum\x85')
'Lorem Ipsum\n'
jaraco.text.read_newlines(filename, limit=1024)
>>> tmp_path = getfixture('tmp_path')
>>> filename = tmp_path / 'out.txt'
>>> _ = filename.write_text('foo\n', newline='', encoding='utf-8')
>>> read_newlines(filename)
'\n'
>>> _ = filename.write_text('foo\r\n', newline='', encoding='utf-8')
>>> read_newlines(filename)
'\r\n'
>>> _ = filename.write_text('foo\r\nbar\nbing\r', newline='', encoding='utf-8')
>>> read_newlines(filename)
('\r', '\n', '\r\n')
jaraco.text.remove_prefix(text, prefix)

Remove the prefix from the text if it exists.

>>> remove_prefix('underwhelming performance', 'underwhelming ')
'performance'

>>> remove_prefix('something special', 'sample')
'something special'
jaraco.text.remove_suffix(text, suffix)

Remove the suffix from the text if it exists.

>>> remove_suffix('name.git', '.git')
'name'

>>> remove_suffix('something special', 'sample')
'something special'
jaraco.text.simple_html_strip(s)

Remove HTML from the string s.

>>> str(simple_html_strip(''))
''

>>> print(simple_html_strip('A <bold>stormy</bold> day in paradise'))
A stormy day in paradise

>>> print(simple_html_strip('Somebody <!-- do not --> tell the truth.'))
Somebody  tell the truth.

>>> print(simple_html_strip('What about<br/>\nmultiple lines?'))
What about
multiple lines?
jaraco.text.substitution(old, new)

Return a function that will perform a substitution on a string

jaraco.text.trim(s)

Trim something like a docstring to remove the whitespace that is common due to indentation and formatting.

>>> trim("\n\tfoo = bar\n\t\tbar = baz\n")
'foo = bar\n\tbar = baz'
jaraco.text.unwrap(s)

Given a multi-line string, return an unwrapped version.

>>> wrapped = wrap(lorem_ipsum)
>>> wrapped.count('\n')
20
>>> unwrapped = unwrap(wrapped)
>>> unwrapped.count('\n')
1
>>> print(unwrapped)
Lorem ipsum dolor sit amet, consectetur adipiscing ...
Curabitur pretium tincidunt lacus. Nulla gravida orci ...
jaraco.text.words(identifier)
jaraco.text.wrap(s)

Wrap lines of text, retaining existing newlines as paragraph markers.

>>> print(wrap(lorem_ipsum))
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad
minim veniam, quis nostrud exercitation ullamco laboris nisi ut
aliquip ex ea commodo consequat. Duis aute irure dolor in
reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla
pariatur. Excepteur sint occaecat cupidatat non proident, sunt in
culpa qui officia deserunt mollit anim id est laborum.

Curabitur pretium tincidunt lacus. Nulla gravida orci a odio. Nullam
varius, turpis et commodo pharetra, est eros bibendum elit, nec luctus
magna felis sollicitudin mauris. Integer in mauris eu nibh euismod
gravida. Duis ac tellus et risus vulputate vehicula. Donec lobortis
risus a elit. Etiam tempor. Ut ullamcorper, ligula eu tempor congue,
eros est euismod turpis, id tincidunt sapien risus a quam. Maecenas
fermentum consequat mi. Donec fermentum. Pellentesque malesuada nulla
a mi. Duis sapien sem, aliquet nec, commodo eget, consequat quis,
neque. Aliquam faucibus, elit ut dictum aliquet, felis nisl adipiscing
sapien, sed malesuada diam lacus eget erat. Cras mollis scelerisque
nunc. Nullam arcu. Aliquam consequat. Curabitur augue lorem, dapibus
quis, laoreet et, pretium ac, nisi. Aenean magna nisl, mollis quis,
molestie eu, feugiat in, orci. In hac habitasse platea dictumst.
jaraco.text.yield_lines(iterable)
jaraco.text.yield_lines(text: str)

Yield valid lines of a string or iterable.

>>> list(yield_lines(''))
[]
>>> list(yield_lines(['foo', 'bar']))
['foo', 'bar']
>>> list(yield_lines('foo\nbar'))
['foo', 'bar']
>>> list(yield_lines('\nfoo\n#bar\nbaz #comment'))
['foo', 'baz #comment']
>>> list(yield_lines(['foo\nbar', 'baz', 'bing\n\n\n']))
['foo', 'bar', 'baz', 'bing']
jaraco.text.layouts.translate(input, translation)
>>> translate('dvorak', to_dvorak)
'ekrpat'
>>> translate('qwerty', to_qwerty)
'x,dokt'

Indices and tables