dimtim-utils 0.1.14

"Dim-Tim, Inc." python utils

dimtim-utils

Python utils for Dim-Tim projects

Documentation

Module: utils

The utils module provides various utility functions and classes for common tasks.

Functions

noop(*args, **kwargs)

A no-operation function that does nothing.

Parameters:

• *args: Any positional arguments.
• **kwargs: Any keyword arguments.

Returns:

• None

Example:

from dimtim.utils import noop

noop()  # Does nothing
noop(1, 2, 3, name='value')  # Also does nothing

Module: debug

The debug module provides tools for measuring and logging execution time of code blocks.

Classes

timeit(tag='-', out=None)

A context decorator for measuring execution time of code blocks.

Parameters:

• tag (str): A tag to identify the timing in the output. Default is -.
• out (Logger, optional): A logger to output the timing information. If None, prints to stdout.

Example:

from dimtim.utils.debug import timeit

# As a context manager
with timeit('database-query'):
    # Code to measure
    result = db.execute_query()

# As a decorator
@timeit('slow-function')
def process_data():
    # Code to measure
    return processed_data

Module: decorators

The decorators module provides useful decorators for Python classes and functions.

Classes

classproperty

A decorator that allows creating properties at the class level.

Example:

from dimtim.utils.decorators import classproperty

class MyClass:
    _value = 10

    @classproperty
    def value(cls):
        return cls._value

# Access the property at the class level
print(MyClass.value)  # Output: 10

cachedproperty

A decorator that caches the result of a property method.

Example:

from dimtim.utils.decorators import cachedproperty

class MyClass:
    @cachedproperty
    def expensive_calculation(self):
        # This will only be calculated once per instance
        return sum(range(10000000))

obj = MyClass()
print(obj.expensive_calculation)  # Calculated
print(obj.expensive_calculation)  # Retrieved from cache

cachedclassproperty

A decorator that combines the functionality of classproperty and cachedproperty.

Example:

from dimtim.utils.decorators import cachedclassproperty

class MyClass:
    @cachedclassproperty
    def expensive_class_calculation(cls):
        # This will only be calculated once for the class
        return sum(range(10000000))

print(MyClass.expensive_class_calculation)  # Calculated
print(MyClass.expensive_class_calculation)  # Retrieved from cache

Functions

freezeargs(fn)

A decorator that freezes dictionary arguments to make them immutable.

Example:

from dimtim.utils.decorators import freezeargs

@freezeargs
def process_config(config):
    # config is now immutable
    # This prevents accidental modification of the config
    return config['value']

Module: duration

The duration module provides functions for working with datetime.timedelta objects.

Functions

duration_string(duration)

Formats a timedelta as a human-readable string.

Parameters:

• duration (timedelta): The duration to format.

Returns:

• A string in the format days hh:mm:ss.microseconds.

Example:

from datetime import timedelta
from dimtim.utils.duration import duration_string

duration = timedelta(days=1, hours=2, minutes=30, seconds=45, microseconds=123456)
print(duration_string(duration))  # Output: "1 02:30:45.123456"

duration_iso_string(duration)

Formats a timedelta as an ISO 8601 duration string.

Parameters:

• duration (timedelta): The duration to format.

Returns:

• A string in the format P1DT02H30M45.123456S.

Example:

from datetime import timedelta
from dimtim.utils.duration import duration_iso_string

duration = timedelta(days=1, hours=2, minutes=30, seconds=45, microseconds=123456)
print(duration_iso_string(duration))  # Output: "P1DT02H30M45.123456S"

duration_microseconds(delta)

Converts a timedelta to microseconds.

Parameters:

• delta (timedelta): The duration to convert.

Returns:

• The duration in microseconds.

Example:

from datetime import timedelta
from dimtim.utils.duration import duration_microseconds

duration = timedelta(seconds=1, microseconds=500000)
print(duration_microseconds(duration))  # Output: 1500000

Module: environ

The environ module provides functions for working with environment variables.

Functions

to_bool(value)

Converts a string, int, or bool value to a boolean.

Parameters:

• value (str, int, bool): The value to convert.

Returns:

• A boolean value.

Example:

from dimtim.utils.environ import to_bool

print(to_bool('true'))    # Output: True
print(to_bool('false'))   # Output: False
print(to_bool('1'))       # Output: True
print(to_bool('0'))       # Output: False

to_int(value, default=None)

Converts a string or int value to an integer, with an optional default.

Parameters:

• value (str, int): The value to convert.
• default (int, optional): The default value to return if conversion fails.

Returns:

• An integer value, or the default if conversion fails.

Example:

from dimtim.utils.environ import to_int

print(to_int('123'))      # Output: 123
print(to_int('abc', 0))   # Output: 0

to_list(value, cast=None, separator=',')

Converts a string to a list, with optional type casting and separator.

Parameters:

• value (str): The string to convert.
• cast (type, optional): A function to cast each item in the list.
• separator (str, optional): The separator to split the string by. Default is ','.

Returns:

• A list of values.

Example:

from dimtim.utils.environ import to_list

print(to_list('a,b,c'))           # Output: ['a', 'b', 'c']
print(to_list('1,2,3', int))      # Output: [1, 2, 3]
print(to_list('a|b|c', separator='|'))  # Output: ['a', 'b', 'c']

get(name, default=None)

Gets a string value from an environment variable.

Parameters:

• name (str): The name of the environment variable.
• default (str, optional): The default value to return if the variable is not set.

Returns:

• A string value, or the default.

Example:

import os
from dimtim.utils.environ import get

os.environ['API_KEY'] = 'abc123'
print(get('API_KEY'))             # Output: abc123
print(get('SECRET', 'default'))   # Output: default

get_bool(name, default=False)

Gets a boolean value from an environment variable.

Parameters:

• name (str): The name of the environment variable.
• default (bool, optional): The default value to return if the variable is not set.

Returns:

• A boolean value.

Example:

import os
from dimtim.utils.environ import get_bool

os.environ['DEBUG'] = 'true'
print(get_bool('DEBUG'))          # Output: True
print(get_bool('NONEXISTENT'))    # Output: False

get_int(name, default=None)

Gets an integer value from an environment variable.

Parameters:

• name (str): The name of the environment variable.
• default (int, optional): The default value to return if the variable is not set or conversion fails.

Returns:

• An integer value, or the default.

Example:

import os
from dimtim.utils.environ import get_int

os.environ['PORT'] = '8000'
print(get_int('PORT'))            # Output: 8000
print(get_int('NONEXISTENT', 80)) # Output: 80

get_list(name, cast=None, separator=',', default=None)

Gets a list value from an environment variable.

Parameters:

• name (str): The name of the environment variable.
• cast (type, optional): A function to cast each item in the list.
• separator (str, optional): The separator to split the string by. Default is ','.
• default (list, optional): The default value to return if the variable is not set.

Returns:

• A list of values, or the default.

Example:

import os
from dimtim.utils.environ import get_list

os.environ['ALLOWED_HOSTS'] = 'localhost,example.com'
print(get_list('ALLOWED_HOSTS'))  # Output: ['localhost', 'example.com']
print(get_list('NONEXISTENT', default=['default']))  # Output: ['default']

Module: hashing

The hashing module provides functions for generating hash values.

Functions

md5(val)

Generates an MD5 hash for a string or bytes value.

Parameters:

• val (str, bytes): The value to hash.

Returns:

• A hexadecimal string of the MD5 hash.

Example:

from dimtim.utils.hashing import md5

print(md5('hello'))  # Output: "5d41402abc4b2a76b9719d911017c592"

sha1(val)

Generates a SHA1 hash for a string or bytes value.

Parameters:

• val (str, bytes): The value to hash.

Returns:

• A hexadecimal string of the SHA1 hash.

Example:

from dimtim.utils.hashing import sha1

print(sha1('hello'))  # Output: "aaf4c61ddcc5e8a2dabede0f3b482cd9aea9434d"

secret_hmac(key, message)

Generates an HMAC-SHA1 hash using a key and message.

Parameters:

• key (str): The secret key.
• message (str): The message to hash.

Returns:

• A hexadecimal string of the HMAC-SHA1 hash.

Example:

from dimtim.utils.hashing import secret_hmac

print(secret_hmac('secret', 'message'))  # Output: HMAC-SHA1 hash

Module: importing

The importing module provides functions for importing modules and classes.

Functions

safe_import(module, silence=True, reraise=False)

Safely imports a module, with options to silence errors or reraise exceptions.

Parameters:

• module (str): The name of the module to import.
• silence (bool, optional): Whether to silence import errors. Default is True.
• reraise (bool, optional): Whether to reraise import errors. Default is False.

Returns:

• The imported module, or None if import fails.

Example:

from dimtim.utils.importing import safe_import

# Import a module that might not be installed
requests = safe_import('requests')
if requests:
    response = requests.get('https://example.com')
else:
    print("Requests module not available")

import_string(path)

Imports a class or function from a module using a string path.

Parameters:

• path (str): The path to the class or function, in the format module.submodule.Class.

Returns:

• The imported class or function.

Example:

from dimtim.utils.importing import import_string

# Import a class from a module
HttpResponse = import_string('django.http.HttpResponse')
response = HttpResponse('Hello, world!')

load_file_as_module(path, name=None, execute=True)

Loads a Python file as a module, with an option to execute it.

Parameters:

• path (str): The path to the Python file.
• name (str, optional): The name to give the module. If None, uses the filename.
• execute (bool, optional): Whether to execute the module. Default is True.

Returns:

• A tuple of (loader, module).

Example:

from dimtim.utils.importing import load_file_as_module

# Load a Python file as a module
loader, module = load_file_as_module('/path/to/script.py')
# Access functions and variables from the module
result = module.some_function()

Module: itertools

The itertools module provides functions for working with iterables.

Functions

chunked(value, size)

A generator function that splits a sequence into chunks of a specified size.

Parameters:

• value (Sequence): The sequence to split.
• size (int): The size of each chunk.

Returns:

• A generator yielding chunks of the sequence.

Example:

from dimtim.utils.itertools import chunked

# Split a list into chunks of size 3
data = [1, 2, 3, 4, 5, 6, 7, 8, 9]
for chunk in chunked(data, 3):
    print(chunk)
# Output:
# [1, 2, 3]
# [4, 5, 6]
# [7, 8, 9]

Module: json

The json module provides enhanced JSON serialization and deserialization.

Classes

JSONEncoder

A custom JSON encoder that can handle various Python types like datetime, decimal, UUID, sets, and custom Serializable objects.

Example:

from dimtim.utils.json import JSONEncoder
import json
from datetime import datetime

data = {
    'date': datetime.now(),
    'set': {1, 2, 3},
    'decimal': decimal.Decimal('10.5'),
    'uuid': uuid.uuid4()
}

json_str = json.dumps(data, cls=JSONEncoder)
print(json_str)

Functions

load(fp, *, cls=None, **kwargs)

Loads JSON from a file-like object.

Parameters:

• fp (file-like object): A file-like object containing JSON.
• cls (JSONDecoder, optional): A custom JSON decoder.
• **kwargs: Additional arguments to pass to json.load.

Returns:

• The deserialized JSON data.

Example:

from dimtim.utils.json import load

with open('data.json', 'r') as f:
    data = load(f)

loads(data, *, cls=None, **kwargs)

Loads JSON from a string.

Parameters:

• data (str, bytes): A string or bytes containing JSON.
• cls (JSONDecoder, optional): A custom JSON decoder.
• **kwargs: Additional arguments to pass to json.loads.

Returns:

• The deserialized JSON data.

Example:

from dimtim.utils.json import loads

json_str = '{"name": "John", "age": 30}'
data = loads(json_str)

dump(obj, fp, *, ensure_ascii=False, cls=None, indent=None, **kwargs)

Dumps an object as JSON to a file-like object.

Parameters:

• obj (Any): The object to serialize.
• fp (file-like object): A file-like object to write the JSON to.
• ensure_ascii (bool, optional): Whether to escape non-ASCII characters. Default is False.
• cls (JSONEncoder, optional): A custom JSON encoder. Default is JSONEncoder.
• indent (int, optional): The number of spaces to indent. Default is None.
• **kwargs: Additional arguments to pass to json.dump.

Example:

from dimtim.utils.json import dump
from datetime import datetime

data = {
    'date': datetime.now(),
    'set': {1, 2, 3}
}

with open('data.json', 'w') as f:
    dump(data, f, indent=2)

dumps(obj, *, ensure_ascii=False, cls=None, indent=None, **kwargs)

Dumps an object as JSON to a string.

Parameters:

• obj (Any): The object to serialize.
• ensure_ascii (bool, optional): Whether to escape non-ASCII characters. Default is False.
• cls (JSONEncoder, optional): A custom JSON encoder. Default is JSONEncoder.
• indent (int, optional): The number of spaces to indent. Default is None.
• **kwargs: Additional arguments to pass to json.dumps.

Returns:

• A JSON string.

Example:

from dimtim.utils.json import dumps
from datetime import datetime

data = {
    'date': datetime.now(),
    'set': {1, 2, 3}
}

json_str = dumps(data, indent=2)
print(json_str)

Module: proxy

The proxy module provides proxy classes for working with objects.

Classes

DictProxy(obj)

A proxy class that inherits from Mapping, Iterable, and list, and wraps a dictionary or object, allowing modifications without changing the original.

Parameters:

• obj (Any): The dictionary or object to wrap.

Example:

from dimtim.utils.proxy import DictProxy

# Create a proxy for a dictionary
original = {'a': 1, 'b': 2}
proxy = DictProxy(original)

# Modify the proxy
proxy['c'] = 3
del proxy['a']

print(proxy)  # Output: {'b': 2, 'c': 3}
print(original)  # Output: {'a': 1, 'b': 2}

# Create a proxy for an object
class MyClass:
    def __init__(self):
        self.a = 1
        self.b = 2

obj = MyClass()
proxy = DictProxy(obj)

# Modify the proxy
proxy.c = 3
del proxy.a

print(proxy.b)  # Output: 2
print(proxy.c)  # Output: 3
print(obj.a)    # Output: 1

Module: random

The random module provides functions for generating random strings and making random choices.

Functions

get_random_string(length, charset=DEFAULT_CHARSET)

Generates a random string of a specified length using a given character set.

Parameters:

• length (int): The length of the string to generate.
• charset (str, optional): The character set to use. Default is DEFAULT_CHARSET.

Returns:

• A random string.

Example:

from dimtim.utils.random import get_random_string

# Generate a random string of length 10
print(get_random_string(10))  # Output: "a1b2c3d4e5"

string4(), string8(), string16(), string32(), string64()

Generate random strings of specified lengths using the default character set.

Returns:

• A random string of the specified length.

Example:

from dimtim.utils.random import string8, string16

print(string8())   # Output: "a1b2c3d4"
print(string16())  # Output: "a1b2c3d4e5f6g7h8"

hex4(), hex8(), hex16(), hex32(), hex64()

Generate random hexadecimal strings of specified lengths.

Returns:

• A random hexadecimal string of the specified length.

Example:

from dimtim.utils.random import hex8, hex16

print(hex8())   # Output: "a1b2c3d4"
print(hex16())  # Output: "a1b2c3d4e5f6g7h8"

string8upper()

Generates a random 8-character string using uppercase letters and digits.

Returns:

• A random 8-character string.

Example:

from dimtim.utils.random import string8upper

print(string8upper())  # Output: "A1B2C3D4"

username(underscores=True)

Generates a random username by combining adjectives and nouns.

Parameters:

• underscores (bool, optional): Whether to use underscores between words. Default is True.

Returns:

• A random username.

Example:

from dimtim.utils.random import username

print(username())  # Output: "happy_blue_sky"
print(username(underscores=False))  # Output: "HappyBlueSky"

choice(variants)

Selects a random item from a sequence.

Parameters:

• variants (Sequence): The sequence to choose from.

Returns:

• A random item from the sequence.

Example:

from dimtim.utils.random import choice

colors = ['red', 'green', 'blue']
print(choice(colors))  # Output: A random color

Module: terminal

The terminal module provides functions for terminal output formatting.

Functions

colorize(text='', opts=(), **kwargs)

Adds ANSI color codes to text, with options for foreground color, background color, and text styles.

Parameters:

• text (str, optional): The text to colorize.
• opts (tuple, optional): A tuple of options like 'bold', 'underscore', etc.
• **kwargs: Keyword arguments for foreground ('fg') and background ('bg') colors.

Returns:

• The colorized text.

Example:

from dimtim.utils.terminal import colorize

print(colorize('Hello', fg='red', bg='blue', opts=('bold',)))
print(colorize('Error', fg='red', opts=('bold',)))
print(colorize('Warning', fg='yellow'))

make_style(opts=(), **kwargs)

Creates a function with default parameters for colorize.

Parameters:

• opts (tuple, optional): A tuple of options like 'bold', 'underscore', etc.
• **kwargs: Keyword arguments for foreground ('fg') and background ('bg') colors.

Returns:

• A function that applies the specified style to text.

Example:

from dimtim.utils.terminal import make_style

# Create style functions
error = make_style(fg='red', opts=('bold',))
warning = make_style(fg='yellow')
info = make_style(fg='blue')

# Use the style functions
print(error('Error message'))
print(warning('Warning message'))
print(info('Info message'))

show_progress(count, total, text='', out=None)

Displays a progress bar in the terminal.

Parameters:

• count (int): The current progress count.
• total (int): The total count for 100% progress.
• text (str, optional): Text to display before the progress bar.
• out (file-like object, optional): A file-like object to write the progress to. If None, prints to stdout.

Example:

from dimtim.utils.terminal import show_progress
import time

total = 100
for i in range(total + 1):
    show_progress(i, total, 'Processing:')
    time.sleep(0.05)

Module: text

The text module provides functions for text manipulation.

Functions

inline(value)

Converts multiline text to a single line.

Parameters:

• value (str): The text to convert.

Returns:

• A single-line string.

Example:

from dimtim.utils.text import inline

text = """
This is a
multiline
text
"""
print(inline(text))  # Output: "This is a multiline text"

slugify(value, allow_unicode=False)

Converts text to a URL-friendly slug.

Parameters:

• value (str): The text to convert.
• allow_unicode (bool, optional): Whether to allow Unicode characters. Default is False.

Returns:

• A slug string.

Example:

from dimtim.utils.text import slugify

print(slugify('Hello World!'))  # Output: "hello-world"
print(slugify('Привет, мир!', allow_unicode=True))  # Output: "привет-мир"

strip_markdown(value)

Removes Markdown formatting from text.

Parameters:

• value (str): The Markdown text to strip.

Returns:

• Plain text without Markdown formatting.

Example:

from dimtim.utils.text import strip_markdown

markdown = "# Title\n\nThis is **bold** and *italic* text."
print(strip_markdown(markdown))  # Output: "Title This is bold and italic text."

to_snake_case(text)

Converts text to snake_case.

Parameters:

• text (str): The text to convert.

Returns:

• A snake_case string.

Example:

from dimtim.utils.text import to_snake_case

print(to_snake_case('HelloWorld'))  # Output: "hello_world"
print(to_snake_case('GetHTTPResponse'))  # Output: "get_http_response"

to_kebab_case(text)

Converts text to kebab-case.

Parameters:

• text (str): The text to convert.

Returns:

• A kebab-case string.

Example:

from dimtim.utils.text import to_kebab_case

print(to_kebab_case('HelloWorld'))  # Output: "hello-world"
print(to_kebab_case('GetHTTPResponse'))  # Output: "get-http-response"

to_camel_case(text)

Converts text to CamelCase.

Parameters:

• text (str): The text to convert.

Returns:

• A CamelCase string.

Example:

from dimtim.utils.text import to_camel_case

print(to_camel_case('hello_world'))  # Output: "HelloWorld"
print(to_camel_case('get-http-response'))  # Output: "GetHttpResponse"

format_size(size)

Formats a file size in bytes to a human-readable string.

Parameters:

• size (int): The size in bytes.

Returns:

• A human-readable size string.

Example:

from dimtim.utils.text import format_size

print(format_size(1024))  # Output: "1.00 Kb"
print(format_size(1048576))  # Output: "1.00 Mb"
print(format_size(1073741824))  # Output: "1.00 Gb"

normalize_email(email)

Normalizes an email address.

Parameters:

• email (str): The email address to normalize.

Returns:

• A normalized email address, or None if the input is not a valid email.

Example:

from dimtim.utils.text import normalize_email

print(normalize_email('[e-mail]'))  # Output: "[e-mail]"
print(normalize_email('invalid'))  # Output: None

normalize_username(username)

Normalizes a username.

Parameters:

• username (str): The username to normalize.

Returns:

• A normalized username.

Example:

from dimtim.utils.text import normalize_username

print(normalize_username('User123'))  # Output: "User123" (normalized Unicode form)

pluralize(locale, value, one, two, five)

Returns the appropriate plural form based on a number and locale.

Parameters:

• locale (str): The locale ('en' or 'ru').
• value (int): The number to determine the plural form for.
• one (str): The form for one item.
• two (str): The form for two items (or few in Russian).
• five (str): The form for five items (or many in Russian).

Returns:

• The appropriate plural form.

Example:

from dimtim.utils.text import pluralize

# English
print(pluralize('en', 1, 'apple', 'apples', 'apples'))  # Output: "apple"
print(pluralize('en', 2, 'apple', 'apples', 'apples'))  # Output: "apples"

# Russian
print(pluralize('ru', 1, 'яблоко', 'яблока', 'яблок'))  # Output: "яблоко"
print(pluralize('ru', 2, 'яблоко', 'яблока', 'яблок'))  # Output: "яблока"
print(pluralize('ru', 5, 'яблоко', 'яблока', 'яблок'))  # Output: "яблок"

Module: timezone

The timezone module provides utilities for working with timezones.

Functions

get_fixed_timezone(offset)

Creates a fixed timezone with a given offset.

Parameters:

• offset (timedelta, int): The timezone offset in minutes or as a timedelta.

Returns:

• A timezone object.

Example:

from dimtim.utils.timezone import get_fixed_timezone
from datetime import timedelta

# Create a timezone with a +2 hour offset
tz = get_fixed_timezone(120)
# Or using a timedelta
tz = get_fixed_timezone(timedelta(hours=2))

get_default_timezone()

Gets the default timezone (from TIME_ZONE environment variable or 'Europe/Moscow').

Returns:

• A timezone object.

Example:

from dimtim.utils.timezone import get_default_timezone

tz = get_default_timezone()

get_default_timezone_name()

Gets the name of the default timezone.

Returns:

• The timezone name as a string.

Example:

from dimtim.utils.timezone import get_default_timezone_name

print(get_default_timezone_name())  # Output: "Europe/Moscow"

get_current_timezone()

Gets the currently active timezone.

Returns:

• A timezone object.

Example:

from dimtim.utils.timezone import get_current_timezone

tz = get_current_timezone()

get_current_timezone_name()

Gets the name of the currently active timezone.

Returns:

• The timezone name as a string.

Example:

from dimtim.utils.timezone import get_current_timezone_name

print(get_current_timezone_name())  # Output: "Europe/Moscow"

activate(timezone)

Activates a timezone.

Parameters:

• timezone (str, tzinfo): The timezone to activate.

Example:

from dimtim.utils.timezone import activate

activate('Europe/London')

deactivate()

Deactivates the current timezone.

Example:

from dimtim.utils.timezone import deactivate

deactivate()

override(timezone)

Context manager for temporarily overriding the current timezone.

Parameters:

• timezone (str, tzinfo): The timezone to activate.

Example:

from dimtim.utils.timezone import override

with override('Europe/London'):
    # Code that uses the London timezone
    pass
# Back to the previous timezone

localtime(value=None, timezone=None)

Converts a datetime to the local timezone.

Parameters:

• value (datetime, optional): The datetime to convert. If None, uses now().
• timezone (tzinfo, optional): The timezone to convert to. If None, uses the current timezone.

Returns:

• A datetime in the local timezone.

Example:

from dimtim.utils.timezone import localtime, now

# Get the current time in the local timezone
local_now = localtime(now())

localdate(value=None, timezone=None)

Gets the date in the local timezone.

Parameters:

• value (datetime, optional): The datetime to convert. If None, uses now().
• timezone (tzinfo, optional): The timezone to convert to. If None, uses the current timezone.

Returns:

• A date in the local timezone.

Example:

from dimtim.utils.timezone import localdate, now

# Get the current date in the local timezone
local_date = localdate(now())

now()

Gets the current UTC datetime.

Returns:

• A timezone-aware datetime in UTC.

Example:

from dimtim.utils.timezone import now

current_time = now()

is_aware(value)

Checks if a datetime is timezone-aware.

Parameters:

• value (datetime): The datetime to check.

Returns:

• True if the datetime is timezone-aware, False otherwise.

Example:

from dimtim.utils.timezone import is_aware, now
from datetime import datetime

print(is_aware(now()))  # Output: True
print(is_aware(datetime.now()))  # Output: False

is_naive(value)

Checks if a datetime is timezone-naive.

Parameters:

• value (datetime): The datetime to check.

Returns:

• True if the datetime is timezone-naive, False otherwise.

Example:

from dimtim.utils.timezone import is_naive, now
from datetime import datetime

print(is_naive(now()))  # Output: False
print(is_naive(datetime.now()))  # Output: True

make_aware(value, timezone=None)

Makes a naive datetime timezone-aware.

Parameters:

• value (datetime): The naive datetime to make aware.
• timezone (tzinfo, optional): The timezone to use. If None, uses the current timezone.

Returns:

• A timezone-aware datetime.

Example:

from dimtim.utils.timezone import make_aware
from datetime import datetime

naive_dt = datetime.now()
aware_dt = make_aware(naive_dt)

make_naive(value, timezone=None)

Makes an aware datetime timezone-naive.

Parameters:

• value (datetime): The aware datetime to make naive.
• timezone (tzinfo, optional): The timezone to convert to before removing the timezone. If None, uses the current timezone.

Returns:

• A timezone-naive datetime.

Example:

from dimtim.utils.timezone import make_naive, now

aware_dt = now()
naive_dt = make_naive(aware_dt)

parse(value, format, timezone=None)

Parses a datetime string with a given format and timezone.

Parameters:

• value (str): The datetime string to parse.
• format (str): The format string.
• timezone (tzinfo, optional): The timezone to use. If None, uses the current timezone.

Returns:

• A timezone-aware datetime.

Example:

from dimtim.utils.timezone import parse

dt = parse('2023-01-01 12:00:00', '%Y-%m-%d %H:%M:%S')

has_overlap(start1, end1, start2, end2)

Checks if two date ranges overlap.

Parameters:

• start1 (datetime, date): The start of the first range.
• end1 (datetime, date): The end of the first range.
• start2 (datetime, date): The start of the second range.
• end2 (datetime, date): The end of the second range.

Returns:

• True if the ranges overlap, False otherwise.

Example:

from dimtim.utils.timezone import has_overlap
from datetime import datetime

# Check if two meetings overlap
meeting1_start = datetime(2023, 1, 1, 10, 0)
meeting1_end = datetime(2023, 1, 1, 11, 0)
meeting2_start = datetime(2023, 1, 1, 10, 30)
meeting2_end = datetime(2023, 1, 1, 11, 30)

print(has_overlap(meeting1_start, meeting1_end, meeting2_start, meeting2_end))  # Output: True

Module: buffer

The buffer module provides utilities for working with in-memory buffers.

Functions

named_bytesio(name, content=None)

Creates a BytesIO object with a name attribute.

Parameters:

• name (str): The name to assign to the BytesIO object.
• content (str, bytes, optional): The content to initialize the BytesIO object with. Default is None.

Returns:

• A BytesIO object with a name attribute.

Example:

from dimtim.utils.buffer import named_bytesio

buffer = named_bytesio('example.txt', b'Hello, world!')
print(buffer.name)  # Output: "example.txt"
print(buffer.getvalue())  # Output: b'Hello, world!'

Module: path

The path module provides utilities for working with file paths.

Functions

fileext(name)

Returns the file extension of a given filename.

Parameters:

• name (str): The filename to extract the extension from.

Returns:

• The file extension (including the dot) of the given filename.

Example:

from dimtim.utils.path import fileext

print(fileext('example.txt'))  # Output: ".txt"

Module: management

The management module provides tools for task management and command execution.

Classes

CommandRunner

A class for managing and executing tasks.

Parameters:

• root (str): The root directory of the project.
• bin_path (str): The path to the directory containing task files, relative to the root.

Methods:

• collect_tasks(): Collects all available tasks from the bin_path directory.
• available_tasks_string(): Returns a string listing all available tasks.
• is_task_exists(name): Checks if a task with the given name exists.
• run(*args): Runs a task with the given arguments.
• set_global_prepare_hook(hook): Sets a global hook that runs before any task.

Example:

from dimtim.helpers.management.runner import CommandRunner

# Create a runner for the current directory with tasks in the 'bin' folder
runner = CommandRunner('/path/to/project', 'bin')

# Run a task
runner.run('task-name', '--arg1', 'value1')

# Set a global prepare hook
CommandRunner.set_global_prepare_hook(lambda: print("Preparing to run a task..."))

CommandBase

A base class for defining tasks.

Methods:

• add_arguments(parser): Add command-line arguments to the parser.
• run(args): Run the task with the given arguments.
• handle(**kwargs): Handle the task execution (must be implemented by subclasses).

Example:

from dimtim.helpers.management.command import CommandBase
from argparse import ArgumentParser

class Command(CommandBase):
    help = 'A sample task that greets a person'

    def add_arguments(self, parser: ArgumentParser):
        parser.add_argument('--name', '-n', default='World', help='Name to greet')

    def handle(self, **kwargs):
        name = kwargs.get('name', 'World')
        self.stdout.write(f"Hello, {name}!")

CronCommand

A base class for defining tasks that can be scheduled with cron.

Attributes:

• comment (str): A comment to identify the cron job.
• schedule (str): The cron schedule expression (default: '* * * * *').

Methods:

• setup_task(): Add the task to the user's crontab.
• remove_task(): Remove the task from the user's crontab.

Example:

from dimtim.helpers.management.cron_command import CronCommand
from argparse import ArgumentParser

class Command(CronCommand):
    help = 'A sample cron task that runs daily'
    comment = 'Daily greeting task'
    schedule = '0 0 * * *'  # Run at midnight every day

    def add_arguments(self, parser: ArgumentParser):
        parser.add_argument('--name', '-n', default='World', help='Name to greet')

    def handle(self, **kwargs):
        name = kwargs.get('name', 'World')
        self.stdout.write(f"Hello, {name}!")

Console Command: dtrun

When the package is installed, it adds a console command dtrun that runs tasks from the 'bin' directory in the current working directory.

Usage:

# List available tasks
dtrun

# Run a specific task
dtrun task-name [arguments]

# Setup a cron task (if the task is a CronCommand)
dtrun cron-task --setup

# Remove a cron task (if the task is a CronCommand)
dtrun cron-task --remove

Adding Tasks:

1. Create a 'bin' directory in your project root.
2. Create a Python file in the 'bin' directory (e.g., 'my-task.py').
3. Define a Command class in the file that inherits from CommandBase or CronCommand.
4. Implement the handle method to define the task's behavior.

Example Project Structure:

my-project/
├── bin/
│   ├── __init__.py
│   ├── hello.py  # Regular task
│   └── daily-report.py  # Cron task
└── other_files_and_directories/

Example Task File (bin/hello.py):

from dimtim.helpers.management.command import CommandBase
from argparse import ArgumentParser

class Command(CommandBase):
    help = 'Greets a person'

    def add_arguments(self, parser: ArgumentParser):
        parser.add_argument('--name', '-n', default='World', help='Name to greet')

    def handle(self, **kwargs):
        name = kwargs.get('name', 'World')
        self.stdout.write(f"Hello, {name}!")

Example Cron Task File (bin/daily-report.py):

from dimtim.helpers.management.cron_command import CronCommand
from argparse import ArgumentParser

class Command(CronCommand):
    help = 'Generates a daily report'
    comment = 'Daily report generation'
    schedule = '0 8 * * *'  # Run at 8 AM every day

    def add_arguments(self, parser: ArgumentParser):
        parser.add_argument('--output', '-o', default='report.txt', help='Output file')

    def handle(self, **kwargs):
        output = kwargs.get('output', 'report.txt')
        # Generate the report
        self.stdout.write(f"Report generated and saved to {output}")

Module: data

The data module contains data used by other modules.

Submodules

wordlists

Contains lists of words used by the random module for generating usernames.

Constants:

• ADJECTIVES: A list of adjective words.
• NOUNS: A list of noun words.

Example:

from dimtim.utils.data.wordlists import ADJECTIVES, NOUNS
import random

# Generate a random adjective-noun pair
print(f"{random.choice(ADJECTIVES)}_{random.choice(NOUNS)}")