API Documentation

class tslist.TSList(iterable=(), /)

Bases: list

TS filtered list

Parameters:

iterable – iterable of items

Returns:

list

The TS filtered list enhances the standard list by filtering the list by slices of types T differing from int in which (before comparision) any item x is converted to type T by calling T(x)

>>> from tslist import TSList

>>> l = 1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 1.8, 1.9
>>> tsl = TSList(l)
>>> tsl
TSList([1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 1.8, 1.9])

>>> tsl[1.0:1.3]  # filter all items between 1.0 (included) and 1.3 (excluded)
TSList([1.0, 1.1, 1.2])

>>> tsl[1.0:1.31]
TSList([1.0, 1.1, 1.2, 1.3])

>>> tsl[1.1]  # filter all items at 1.1
TSList([1.1])

>>> tsl.append(1.1)
>>> tsl[1.1]
TSList([1.1, 1.1])

This becomes even more handy if list items admit conversions.

>>> from datetime import timedelta, datetime
>>> from tslist import TS

>>> class Timedelta(timedelta):
...     def __float__(self):
...         return self.total_seconds()
...
...     def __ts__(self):
...         # used for conversion using tslist.TS
...         return datetime(2000, 1, 1) + self

>>> l = [Timedelta(d) for d in range(10, 15)]
>>> tsl = TSList(l)
>>> tsl
TSList(
[ Timedelta(days=10),
  Timedelta(days=11),
  Timedelta(days=12),
  Timedelta(days=13),
  Timedelta(days=14)]
)

>>> list(map(float, tsl))
[864000.0, 950400.0, 1036800.0, 1123200.0, 1209600.0]

>>> tsl[950400.:1209600.:2]
TSList([Timedelta(days=11), Timedelta(days=13)])

>>> list(map(TS, tsl))
[TS(20000111), TS(20000112), TS(20000113), TS(20000114), TS(20000115)]

>>> tsl[TS(20000112):TS(20000114)]
TSList([Timedelta(days=11), Timedelta(days=12)])

See tslist.ts.TS for more detail on timestamp and datetime conversion.

astype(dtype)

more TS Classes

class tslist.TS(year: date | datetime | str | int | float | object | None = None, month: int | None = None, day: int | None = None, hour: int = 0, minute: int = 0, second: int = 0, microsecond: int = 0, tzinfo: tzinfo | None = None, *, fold: int = 0)

Bases: datetime

variation of datetime

Parameters:

• year – (date, datetime, str, int, float or None) year of date or some value to parse the whole date. If year is None it is replaces by tslist.ts.TS.DEFAULT, and if tslist.ts.TS.DEFAULT is None TS.now() is returned. (optional: default is None)

• month – (int or None)

• day – (int or None)

• hour – (int)

• minute – (int)

• second – (int)

• microsecond – (int)

• tzinfo – (tzinfo)

• fold – (int)

tslist.ts.TS differs from datetime only by creating, conversion and representation.

>>> from tslist import TS
>>> TS.DEFAULT = 20201012
>>> TS()
TS(20201012)

>>> TS('20201013')
TS(20201013)

>>> int(TS(20201013))
20201013

>>> TS(20201013.012345)
TS(20201013.012345)

>>> TS(20201013.012345).datetime()
datetime.datetime(2020, 10, 13, 1, 23, 45)

>>> TS(datetime(2020, 10, 13, 1, 23, 45))
TS(20201013.012345)

DEFAULT = None

default datetime for tslist.ts.TS; if ‘None’ tslist.ts.TS returns current date and time

classmethod map(iterable)

datetime()

timestamp as standard datetime.datetime()

class tslist.TSDiff(days: int | str | timedelta = 0, seconds: int = 0, microseconds: int = 0, milliseconds: int = 0, minutes: int = 0, hours: int = 0, weeks: int = 0, *, origin: date | datetime = None)

Bases: timedelta

enhanced timedelta object

Parameters:

• days

• seconds

• microseconds

• milliseconds

• minutes

• hours

• weeks

• origin

Enhances timedelta by additonal properts origin in order to recover difference of creation as

>>> from tslist import TS, TSDiff
>>> tsdiff = TS(20211221) - TS(20211212)
>>> tsdiff
TSDiff('9d', origin=TS(20211212))

>>> tsdiff.origin
TS(20211212)

>>> tsdiff.origin + tsdiff
TS(20211221)

>>> tsdiff * 2
datetime.timedelta(days=18)

>>> tsdiff + tsdiff
datetime.timedelta(days=18)

origin

class tslist.TSDict(iterable=(), /, **kwargs)

Bases: dict

TS filtered list

Parameters:

iterable – iterable of items

Returns:

dict

The TS filtered dict enhances the standard dict by filtering the dict keys by slices of types T differing from int in which (before comparision) any item x is converted to type T by calling T(x)

>>> from tslist import TSDict

>>> d = {1.0: 'a', 1.1: 'b', 1.2: 'c', 1.3: 'd', 1.4: 'e', 1.5: 'f', 1.6: 'g', 1.7: 'h', 1.8: 'i', 1.9: 'j'}
>>> tsd = TSDict(d)
>>> tsd
TSDict(
{ 1.0: 'a',
  1.1: 'b',
  1.2: 'c',
  1.3: 'd',
  1.4: 'e',
  1.5: 'f',
  1.6: 'g',
  1.7: 'h',
  1.8: 'i',
  1.9: 'j'}
)

>>> tsd[1.3]
'd'

>>> tsd[1.0:1.3]  # filter all items between 1.0 (included) and 1.3 (excluded)
TSDict({1.0: 'a', 1.1: 'b', 1.2: 'c'})

>>> tsd[1.0:1.31]
TSDict({1.0: 'a', 1.1: 'b', 1.2: 'c', 1.3: 'd'})

>>> tsd[1.1]  # filter all items at 1.1
'b'

>>> tsd.update({1.1: 'A'})
>>> tsd[1.1]
'A'

This becomes even more handy if list items admit conversions.

>>> from datetime import timedelta, datetime
>>> from tslist import TS

>>> class Timedelta(timedelta):
...     def __float__(self):
...         return self.total_seconds()
...
...     def __ts__(self):
...         # used for conversion using tslist.TS
...         return datetime(2000, 1, 1) + self

>>> d = {Timedelta(t): t for t in range(10, 15)}
>>> tsd = TSDict(d)
>>> tsd
TSDict(
{ Timedelta(days=10): 10,
  Timedelta(days=11): 11,
  Timedelta(days=12): 12,
  Timedelta(days=13): 13,
  Timedelta(days=14): 14}
)

>>> list(map(float, tsd.keys()))
[864000.0, 950400.0, 1036800.0, 1123200.0, 1209600.0]

>>> tsd[950400.:1209600.:2]
TSDict({Timedelta(days=11): 11, Timedelta(days=13): 13})

>>> list(map(TS, tsd.keys()))
[TS(20000111), TS(20000112), TS(20000113), TS(20000114), TS(20000115)]

>>> tsd[TS(20000112):TS(20000114)]
TSDict({Timedelta(days=11): 11, Timedelta(days=12): 12})

See tslist.ts.TS for more detail on timestamp and datetime conversion.

astype(dtype)

class tslist.TSDir(path: Path | str = '', *, read_only=True, verbose=1, cwd='')

Bases: object

TS directory that behaves like a tslist.tsdict.TSDict

Parameters:

• path – root of directory

• read_only – if False directory content may be created, changed and removed (optional; default is True)

• verbose – set level of verbosity. A value of 0 will be silent (no logging), 1 (default) will warn on errors to stderr but no info and 2 prints info messsages to stdout 3 will also raise exceptions on warnings

• cwd – working directory

>>> from tslist import TSDir

setup new storage directory

>>> d = TSDir('test/TESTDIR', read_only=False)

Create relative subdirectories by

>>> s1 = d('SUBDIR1')
>>> s2 = d('SUBDIR2')

Add content

>>> s1['2024-12-25'] = {'name': '1st Christmas Day'}
>>> s1['2024-12-26'] = {'name': '2nd Christmas Day'}

and retrieve it

>>> s2['2024-12-24'] = {'name': 'Christmas Eve'}
>>> s2['2024-12-31'] = {'name': 'New Years Eve'}

>>> s1.keys()
TSList(['2024-12-25', '2024-12-26'])

>>> s1.values()
({'name': '1st Christmas Day'}, {'name': '2nd Christmas Day'})

>>> s2[:]
TSDict(
{ '2024-12-24': {'name': 'Christmas Eve'},
  '2024-12-31': {'name': 'New Years Eve'}}
)

>>> s2['2024-12-24']
{'name': 'Christmas Eve'}

Get an overview of all dirs and items

>>> d.tree()
TESTDIR
├─ SUBDIR1 [2024-12-25 ... 2024-12-26] [2]
└─ SUBDIR2 [2024-12-24 ... 2024-12-31] [2]

Move the directory

>>> d = d.move('test/TESTDIR2')
>>> TSDir('test/TESTDIR').tree()

>>> d
TSDir('test/TESTDIR2')

>>> d.tree()
TESTDIR2
├─ SUBDIR1 [2024-12-25 ... 2024-12-26] [2]
└─ SUBDIR2 [2024-12-24 ... 2024-12-31] [2]

Remove subdir

>>> d.remove('SUBDIR1')
>>> d.tree()
TESTDIR2
└─ SUBDIR2 [2024-12-24 ... 2024-12-31] [2]

Remove even the directory itself

>>> d.remove()
>>> d.tree()

classmethod from_home(path='', *, read_only=True, verbose=1, cwd='')

open the directory relative to home directory

property name

name of the directory

property path

pathlib.Path object to the directory

property cwd

current working directory

keys()

(see dict.keys)

values()

(see dict.values)

items()

(see dict.items)

update(iterable=(), **kwargs)

(see dict.update)

pop(key)

(see dict.pop)

popitem(key)

(see dict.popitem)

setdefault(key, default=None)

(see dict.setdefault)

get(key, default=None)

(see dict.get)

subdir(**kwargs)

opens subdirectory (and may create it)

move(target)

moves the directory to another path

remove(path='')

removes (deletes) the directory

tree(*func, print=<built-in function print>, limit=1000)

prints a visual tree structure of the directory

class tslist.TSClient(path='', *, verbose=1, token='', host='127.0.0.1', port='5000')

Bases: object

tslist.tsdir.TSDir like client for remote tslist.tsdir.TSDir

Parameters:

• path – route to data on remote directory

• verbose – verbosity of logging

• token – token to access remote directory

• host – host address of remote directory

• port – port of remote directory

>>> from tslist import api, TSClient

To start a remote directory run

$ python -m flask --app "tslist:api('DB/ROUTE', 'token1', ...)" run

For more about runnig a flask server see flask

>>> client = TSClient('DB/ROUTE', token='token1')
>>> client
TSClient('DB/ROUTE', verbose=1, token='token1', host='127.0.0.1', port='5000')

>>> client.subdir()  
['SUBDIR1', 'SUBDIR2']

>>> client.tree()  
ROUTE
├─ SUBDIR1 [2025-01-01 ... 2025-01-05] [5]
└─ SUBDIR2 [2025-01-01 ... 2025-01-05] [5]

>>> sub = client('SUBDIR1')
>>> sub
TSClient('DB/ROUTE/SUBDIR1', verbose=1, token='token1', host='127.0.0.1', port='5000')

>>> sub['2025-01-03']  
{'object at': '2025-01-03'}

>>> sub['2025-01-03': '2025-01-04']  
{
    '2025-01-03': {'object at': '2025-01-03'},
    '2025-01-04': {'object at': '2025-01-04'}
}

TIMEOUT = 30

property name

property path

property url

keys()

values()

items()

subdir(**kwargs)

tree(print=<built-in function print>)

class tslist.TSObject(**kwargs)

Bases: object

generic object with key word arguments and conversion config

Parameters:

kwargs – dict of arguments

>>> from tslist import TS, TSObject

setup object attributes

>>> obj = {'a': 1, 'b': 0.0, 'c': 3, 'd': 4, 'f': '20121124', 'e': 'My Name'}

and define dunder defaults

>>> dunder = {'__bool__':'b', '__int__':'c', '__float__':'d', '__ts__': 'f'}

to create object with conversion configs

>>> d = TSObject(**obj, **dunder, __str__='e', __date__='f')
>>>
>>> d
TSObject(a=1, b=0.0, c=3, d=4, f='20121124', e='My Name', __bool__='b', __int__='c', __float__='d', __ts__='f', __str__='e', __date__='f')

Now, type conversion works as declared

>>> repr(d)
"TSObject(a=1, b=0.0, c=3, d=4, f='20121124', e='My Name', __bool__='b', __int__='c', __float__='d', __ts__='f', __str__='e', __date__='f')"

>>> str(d)
'My Name'

>>> bool(d)
False

>>> int(d)
3

>>> float(d)
4.0

>>> dict(d)
{'a': 1, 'b': 0.0, 'c': 3, 'd': 4, 'f': '20121124', 'e': 'My Name'}

>>> list(d)
[('a', 1), ('b', 0.0), ('c', 3), ('d', 4), ('f', '20121124'), ('e', 'My Name')]

>>> TS(d)
TS(20121124)

>>> d.__date__()
datetime.date(2012, 11, 24)

And cloning instances works in various ways

>>> TSObject(**d.__dict__)
TSObject(a=1, b=0.0, c=3, d=4, f='20121124', e='My Name', __bool__='b', __int__='c', __float__='d', __ts__='f', __str__='e', __date__='f')

>>> from copy import copy
>>>
>>> copy(d)
TSObject(a=1, b=0.0, c=3, d=4, f='20121124', e='My Name', __bool__='b', __int__='c', __float__='d', __ts__='f', __str__='e', __date__='f')

>>> from pickle import dumps, loads
>>>
>>> loads(dumps(d))
TSObject(a=1, b=0.0, c=3, d=4, f='20121124', e='My Name', __bool__='b', __int__='c', __float__='d', __ts__='f', __str__='e', __date__='f')

>>> from json import dumps, loads
>>>
>>> loads(dumps(dict(d)))
{'a': 1, 'b': 0.0, 'c': 3, 'd': 4, 'f': '20121124', 'e': 'My Name'}

Parser Functions

tslist.parser.parse_datetime(item: object | str | int | float | date | datetime | None = None, default: object | str | int | float | date | datetime | None = None) → datetime

tslist.parser.parse_timedelta(item: str, with_months: bool | type = False) → timedelta

parsing string to timedelta

Parameters:

• item – string to parse

• with_months – subtype of ‘timedelta’ witch admits a ‘month’ argument

Returns:

timedelta or subtype of timedelta instance

>>> from tslist.parser import parse_timedelta

>>> parse_timedelta('1.3 days')
datetime.timedelta(days=1, seconds=25920)

>>> parse_timedelta('-1s4µs')
datetime.timedelta(days=-1, seconds=86399, microseconds=4)

>>> parse_timedelta('2 hours 4 Minutes 8 Sec')
datetime.timedelta(seconds=7448)

>>> parse_timedelta('2h4i8s')
datetime.timedelta(seconds=7448)

>>> with_months = lambda *_, months=0: print(timedelta(*_), months)
>>> parse_timedelta('1y 3quarters 1m', with_months=with_months)
0:00:00 22.0