Skip to content
This repository has been archived by the owner on Apr 17, 2024. It is now read-only.

Latest commit

 

History

History
171 lines (149 loc) · 11.4 KB

README-ru.md

File metadata and controls

171 lines (149 loc) · 11.4 KB

Документация на русском

Datify

Этот модуль позволяет извлекать даты из пользовательского ввода. Обработка строк осуществляется через класс Datify.

Поддерживаемые языки:

Установка

Просто выполните pip install datify из командной строки (pip должен быть установлен).

Класс:

Datify(user_input, year, month, date) : принимает user_input: str при создании. Также может принимать именованые аргументы year, month и day вместе с user_input или без него. Если ни один параметр не задан, поднимает ValueError. См. секцию Форматы, чтобы ознакомиться со стандартными форматами Datify.

Методы класса:

Статические:

  1. find_date(string) : Принимает str. Возвращает подстроку с датой в формате General Date Format если она содержится в заданной строке. Иначе возвращает None.
  2. is_year(year) : Принимает str или int. Возвращает True если заданый параметр соответствует формату Digit Year Format.
  3. is_digit_month(month) : Принимает str или int. Возвращает True если заданый параметр соответствует формату Digit Month Format.
  4. is_alpha_month(string) : Принимает str. Возвращает True если заданная строка содержится в словаре названий месяцев. Для языков, в которых есть падежи (русский, украинский) в основном достаточно иметь в словаре только именительную форму слова.
  5. get_alpha_month(string) : Принимает str. Возвращает int - номер месяца в заданой строке согласно словарю. Если строка не содержит известное имя месяца, врозвращает None.
  6. is_day(day) : Принимает str или int. Возвращает True если заданый параметр соответствует формату Day Format.
  7. is_date(date) : Принимает str или int. Возвращает True если заданый параметр соответствует формату General Date Format (См. секцию Форматы).
  8. is_date_part(string) : Принимает str. Возвращает True если заданый параметр содержит хотя бы одну часть даты - день, месяц (номер или название) или год.

Методы экземпляра:

  1. date() : Возвращает datetime object из параметров экземпляра Datify. Если были получены не все нужные параметры (year, month и day), daytime поднимает TypeError.
  2. tuple() : Возвращает кортеж из всех известных параметров. Если месяц или день не заданы, нет никакого способа определить, что именно находится в кортеже после того, как он был получен!
  3. date_or_tuple() : Возвращает datetime object, если известны все нужные параметры. Иначе возвращает кортеж из известных параметров.
  4. set_year(year) : Принимает str или int. Извлекает год из полученной переменной и устанавливает поле year вызванного экземпляра Datify. Если полученный параметр не соответствует формату Year Format, поднимает ValueError. Если год получен в сокращенном формате YY, это считается как 20YY.
  5. set_month(month) : Принимает str или int. Извлекает месяц из полученной переменной и устанавливает поле month вызванного экземпляра Datify. Если полученный параметр не соответствует формату Digit/Alpha Month Format, поднимает ValueError.
  6. set_day(day) : Принимает str или int. Извлекает день из полученной переменной и устанавливает поле day вызванного экземпляра Datify. Если полученный параметр не соответствует формату Day Format, поднимает ValueError.

Форматы:

Обратите внимание, что в этом модуле день проверяется первым, а месяц - после него. 06.07.2021 будет распознано как 6 июля 2021 года!

  • Формат General Date: '[12][01]\d\d[01]\d[0123]\d$' - ГГГГММДД - напр. 20210706 - 6 июля 2021
  • Форматы дня: 0 < день <= 31
    • Для случаев, когда строка содержит только цифры: '[0123]?\d$' - Д?Д - напр. 13, 05, 6 и т.д.
    • Для случаев, когда день задан буквенно-цифровой строкой: '[0123]?\d\D+$' - напр. 1st, 2nd, 25th, 3-е и т.д.
  • Форматы месяца: 0 < месяц <= 12
    • Для случаев, когда строка содержит только цифры: '[01]?\d$' - M?M - напр. 06, 7 и т.д.
    • Для случаев, когда день задан буквенно-цифровой строкой: сравнивает строку со словарём и пытается найти похожее название месяца.
  • Формат Year Format: '([012]\d\d\d$)|(\d\d$)' - ГГГГ or ГГ - напр. 2021 или 21.

    Обратите внимание, что если год задан в виде ГГ, это считается как 20ГГ.

Настройка:

После импорта модуля есть возможность настроить список разделителей и изменить все стандартные форматы, обращаясь к ним через Datify.config['KEY']. №. Имя : КЛЮЧ -- описание

  1. Разделители : 'SPLITTERS' -- множество разделителей для Datify._getWordsList. Содержит , ., - и / по умолчанию.
  2. Форматы (См. секцию Форматы) :
  • Digit Day : 'FORMAT_DAY_DIGIT'
  • Alpha-numeric Day : 'FORMAT_DAY_ALNUM'
  • Digit Month : 'FORMAT_MONTH_DIGIT'
  • Digit Year : 'FORMAT_YEAR_DIGIT'
  • General Date : 'FORMAT_DATE'
  1. День проверяется первым? : 'DAY_FIRST' -- bool. Если True, то первым проверяется день. Если False, то первым проверяется месяц. По умолчанию True.

Например:

Datify('17_06_2021')  # ValueError
Datify.config['SPLITTERS'].add('_')  # Добавляем нужный разделитель в конфиг
Datify('17_06_2021')  # <Datify object (17, 6, 2021)>

Изменение порядка проверки дня и месяца:

Datify('10.12').month  # 12
Datify.config['DAY_FIRST'] = False
Datify('10.12').month  # 10

Примеры:

Я буду каждый раз использовать разные форматы даты, чтобы показать, что Datify может работать с каждым из них. Начнём!

from datify import Datify  # Импортируем главный класс. Все последуюющие действия будут с ним.
  1. Извлечение даты из строки с помощью Datify
user_input = '06.07.2021'  # Имитируем пользовательский ввод. День идет первым!
Datify(user_input)  # <Datify object (6, 7, 2021)>

Таким образом можно обработать любую строку.

  1. Получение отдельных частей даты из Datify
user_input = '06/07'
val = Datify(user_input)

date_day = val.day  # 6
date_month = val.month  # 7
date_year = val.year  # None
  1. Получение даты в экземпляре datetime
user_input = '06-07-21'
date = Datify(user_input).date()  # 2021-07-06 00:00:00

Если дата не будет получена полностью (год, месяц и день), datetime поднимет TypeError:

user_input = '06/07'
date = Datify(user_input).date()  # TypeError: an integer is required (got type NoneType)

Лучше использовать другие способы, если есть шанс получить неполную дату.

  1. Получение кортежа из всех значений: Порядок значений: день, месяц, год
user_input = '6th of July 2021'
Datify(user_input).tuple()  # (6, 7, 2021)

user_input = '6th of July'
Datify(user_input).tuple()  # (6, 7, None)
  1. Получение номера месяца из его названия без создания экземпляра Datify
Datify.get_alpha_month('february')  # 2
  1. Разнообразные проверки для строк
# Любая часть даты
Datify.is_date_part('6')  # True (может быть днём или месяцем)
Datify.is_date_part('31')  # True
Datify.is_date_part('june')  # True
Datify.is_date_part('jan')  # True
Datify.is_date_part('33')  # True (может быть годом в виде `ГГ`)
Datify.is_date_part('333')  # False
Datify.is_date_part('3131')  # False (не соответствует формату года (от `1000` до `2199`))

# Дата в формате General Date
Datify.is_date('20210607')  # True

# Определённые части даты

# Год
Datify.is_year('2021')  # True
Datify.is_year('221')  # False

# Месяц
Datify.is_digit_month('11')  # True (0 < str <= 12)
Datify.is_alpha_month('June')  # True

# День
Datify.is_day('13')  # True (0 < str <= 31)
  1. Поиск даты в формате General Date в любой строке
user_input = 'created "20200120"'
Datify.find_date(user_input)  # '20200120'
  1. Изменение параметров существующего экземпляра Datify
date = Datify('6th of July, 2021')  # <Datify object (6, 7, 2021)>
date.set_year(2018)
print(date.date())  # 2018-07-06 00:00:00

Также можно вручную переопределить параметры обьекта Datify при его создании:

Datify('6th of July, 2021', year=2018, month=3)  # <Datify object (6, 3, 2018)>