democritus-project / d8s-dates

Democritus functions for working with dates and times.

Democritus Dates

Democritus functions^[1] for working with and using dates and times.

[1] Democritus functions are simple, effective, modular, well-tested, and well-documented Python functions.

We use d8s (pronounced "dee-eights") as an abbreviation for democritus (you can read more about this here).

Installation

pip install d8s-dates

Usage

You import the library like:

from d8s_dates import *

Once imported, you can use any of the functions listed below.

Functions

• def date_string_to_strftime_format(date_string):
      """Predict the strftime format from the given date_string."""

• def date_parse(date, *, convert_to_current_timezone: bool = False):
      """Parse the given date (can parse dates in most formats) (returns a datetime object)."""

• def date_now(*, convert_to_current_timezone: bool = False, utc: bool = False):
      """Get the current date.
  
  If convert_to_current_timezone is True, convert the date to the current timezone.
  If utc is True, convert the date to UTC."""

• def date_parse_first_argument(func):
      """."""

• def date_2_string(date, date_format_string: str):
      """."""

• def date_hour(date):
      """Find the hour from the given date."""

• def date_minute(date):
      """Find the minute from the given date."""

• def date_second(date):
      """Find the second from the given date."""

• def date_day(date):
      """Find the day of the month from the given date."""

• def date_day_of_month(date):
      """Find the day of the month from the given date."""

• def date_month(date):
      """Find the month from the given date."""

• def date_year(date):
      """Find the year from the given date."""

• def date_convert_to_timezone(date, timezone_string):
      """Convert the given date to the given timezone_string.
  
  This will actually **convert** time given date; it will change the hour/day of the date to the given timezone)."""

• def date_make_timezone_aware(datetime_object, timezone_string=None):
      """Make the given datetime_object timezone aware.
  
  This function does NOT convert the datetime_object.
  It will never change the hour/day or any value of the datetime...
    it will simply make the given datetime timezone aware."""

• def time_delta_examples(n=10, *, time_deltas_as_strings: bool = True):
      """Return n time deltas."""

• def time_examples(n=10, *, times_as_strings: bool = True):
      """Return n times."""

• def date_examples(n=10, *, dates_as_strings: bool = True, date_string_format: str = None):
      """Return n dates."""

• def datetime_examples(n=10, *, datetimes_as_strings: bool = True, datetime_string_format: str = None):
      """Return n datetimes."""

• def time_struct_to_datetime(struct_time_object):
      """Convert a python time.struct_time object into a datetime object."""

• def epoch_time_now():
      """Get the current epoch time."""

• def is_date(possible_date_string):
      """Determine if the given possible_date_string can be processed as a date."""

• def time_now():
      """Return the current, epoch time."""

• def time_since(date):
      """Return a time of the time since the given date."""

• def time_until(date):
      """Return an English description of the time since the given date."""

• def time_since_slang(date):
      """Return an English description of the time since the given date."""

• def time_until_slang(date):
      """Return an English description of the time until the given date."""

• def date_to_utc(date):
      """Convert the given date to UTC. Assume that the given date is in the system's timezone and convert it to UTC."""

• def time_after(time_a, time_b=None) -> bool:
      """Check if one time is before the other."""

• def time_before(time_a, time_b=None) -> bool:
      """Check if one time is before the other."""

• def date_in_future(date) -> bool:
      """Return whether or not the given date is in the future."""

• def time_is() -> str:
      """Time and money spent in helping men to do more for themselves is far better than mere giving. -Henry Ford"""

• def date_to_iso(date, *, timezone_is_utc: bool = False, use_trailing_z: bool = False):
      """Return the ISO 8601 version of the given date as a string (see https://en.wikipedia.org/wiki/ISO_8601)."""

• def epoch_time_standardization(epoch_time):
      """Convert the given epoch time to an epoch time in seconds."""

• def epoch_to_date(epoch_time):
      """Convert the epoch_time into a datetime."""

• def date_day_of_week(date):
      """Return the day of the week on which the given date occurred."""

• def date_week_of_year(date, *, sunday_is_first_day_of_week: bool = False):
      """Find the week of the year for the given date. If no date is given, return the week of the current date."""

• def date_to_epoch(date):
      """Convert a datetime stamp to epoch time."""

• def chrome_timestamp_to_epoch(chrome_timestamp):
      """Convert the given Chrome timestamp to epoch time.
  
  For more information, see: https://stackoverflow.com/questions/20458406/what-is-the-format-of-chromes-timestamps."""

• def time_waste(n=3):
      """If time be of all things the most precious, wasting time must be the greatest prodigality. -Benjamin Franklin"""

• def time_as_float(time_string: str) -> float:
      """converts a given HH:MM time string to float"""

Development

👋  If you want to get involved in this project, we have some short, helpful guides below:

• contribute to this project 🥇
• test it 🧪
• lint it 🧹
• explore it 🔭

If you have any questions or there is anything we did not cover, please raise an issue and we'll be happy to help.

Credits

This package was created with Cookiecutter and Floyd Hightower's Python project template.

d8s-dates's Issues

Update travis ci to use docker config/scripts

When testing this library in travis CI, I would like to use the same commands used to run the linters/tests in docker.

Document the "dev" docker-compose service

Improve the way we are getting list of days, months, etc.

Look for a better way to get this info: https://github.com/democritus-project/democritus-dates/blob/main/democritus_dates/dates_and_times.py#L18 .

Use map_first_arg function from decorators

The date_parse function should be decorated with map_first_arg.

Update the keywords in the setup.py

Update "date_now" function to handle bad arguments

HELP WANTED 👋 : If you'd like to take this challenge on, please let me know! Even if you're new to Python and/or github, this is a great place to start and I'd be happy to help walk you through this challenge as much as you need - don't hesitate to ask.

This particular issue will give you some exposure to raising exceptions based on the keyword arguments given to a function.

---

The date_now function, takes two, keyword arguments:

• convert_to_current_timezone
• utc

If they are both True, the function should raise an exception because it isn't clear what the user wants to do (should we make the date timezone aware based on the current timezone or UTC?). Please update the date_now function to raise an error if both convert_to_current_timezone and utc are True.

Re-enable and fix failing tests

In 905ce31 I disabled some failing tests. I'd like to re-enable them and fix the underlying problems.

Write function to calculate half-birthday

HELP WANTED 👋 : If you'd like to take this challenge on, please let me know! Even if you're new to Python and/or github, this is a great place to start and I'd be happy to help walk you through this challenge as much as you need - don't hesitate to ask.

This particular issue will give you some exposure to writing a relatively simple function, working with dates in Python, and writing some tests.

---

What?

I would like a function to calculate a half birthday. It should be implemented based on the more precise method described in Wikipedia:

The more precise method is to add or subtract half the number of days in a year to the birth date. In the case of a common year, this would be 182.5 days. In leap years, the number of days would be 183. This method would lead to a March 1 or February 29 half-birthday for an August 31st birthday, depending on whether it's a leap year.

A couple other thoughts:

• The function should be wrapped with the @date_parse_first_argument decorator so that it can take a datetime object or a string in a parsable date format
• The function should return a datetime.date or datetime.datetime object (I'll leave it up to you, but am happy to give some input if needed)

Why?

This is a fun function to have 😄

How?

I can give some implementation guidance if needed. Otherwise, you got this!

Add docs for how to develop this library

Fix lint errors in this library

Update requirements.txt to import packages from pypi rather than github

Consider removing C0301 from list of disabled pylint settings

Currently, we are disabling messages of type C0301 ("Line too long"). Consider re-enabling this.

Use functions from numbers_wrapper and decorators

Once numbers functions and decorators are added, update this code to use the functions from those packages rather than have them locally.

• The number_zero_pad function should be removed and imported from numbers_wrapper.
• The date_parse_first_argument function (a decorator) should be imported from decorators

Rename project repo

Rename from dem_dates/dem-dates to democritus_dates/democritus-dates

Review/fix test failures

Write `time_as_float` function to convert a time to a float (e.g. 12:30 -> 12.5)

HELP WANTED: If you'd like to take this challenge on, please let me know! Even if you're new to Python and/or github, this is a great place to start and I'd be happy to help walk you through this challenge as much as you need - don't hesitate to ask.

---

Description

It would be helpful to have a function to convert a time (e.g. 12:30) to a float (e.g. 12.5) where the value after the decimal point represents the percent of the hour that has gone by.

Examples

Input	Output
12:00	12.0
12:10	12.1666...7
12:15	12.25
12:30	12.5
12:45	12.75

Suggested Function Signature

I imagine the function signature being:

def time_as_float(time_string: str) -> float:
    ...

If you have any thoughts or suggestions, I'm open to input.

Add tests to test edge-cases for the "time_as_float" function

HELP WANTED 👋 : If you'd like to take this challenge on, please let me know! Even if you're new to Python and/or github, this is a great place to start and I'd be happy to help walk you through this challenge as much as you need - don't hesitate to ask.

This particular issue will give you some exposure to using pytest to test functions (specifically to test error handling in a function).

---

We recently added the time_as_float function (#8) which is used like:

time_as_float("12:30")  # 12.5

As you can see in the function's code, the function does a nice job of raising an error if it gets bad input (like "abc" or "a:b").

We should write tests to make sure that errors are raised when bad input is given. So, the goal of this issue is to write tests that:

1. Give bad input into the time_as_float function
2. Validate that the appropriate exception is raised (hint: pytest has a good way of doing this documented here)

If you are interested in working on this issue, but need some more guidance on where/how to start, please comment on this issue and I'll be happy to help!

Consider implementing n_{}_ago functions (e.g. "n_hours_ago")

code execution backdoor

We discovered a potential code execution backdoor in version 0.1.0 of the project, the backdoor is the democritus-hypothesis package. Attackers can upload democritus-hypothesis packages containing arbitrary malicious code. For the safety of this project, the democritus-hypothesis package has been uploaded by us.

The democritus-hypothesis package can be successfully installed using pip install d8s-dates==0.1.0

Suggestion: remove version 0.1.0 of this project in PyPI