Project: tense
License: Apache 2.0
About: Time Processing Tool
OS: Independent
Python: 3.9+
Typing: Typed
Topic: Utilities

Documentation · Report Bug · Request Feature

Table of Contents

1. About The Project
   • Welcome
2. Getting Started
   • With Pip
   • With Poetry
3. Usage
   • Built-in basics
   • Reconfiguring existing settings
   • Adding new settings
   • FAQ
4. Examples
5. Contributing
6. License
7. Contact
8. Acknowledgments
9. Project history

About The Project

Welcome

Have you ever needed to convert, for example, the string "1d1minute 2 sec" to the number of seconds or a datetime.timedelta object?

No? Then advise us to your friends :) And if you really need our tool - let's move on!

Getting started

With PyPi

$ pip3 install tense

With Poetry

$ poetry add tense

Usage

Built-in basic

import datetime
from tense import TenseParser

time_string = "1d2minutes 5 sec"

# <-- Digit parser -->
digit_parser = TenseParser(TenseParser.DIGIT)
assert digit_parser.parse(time_string) == 86525

# <-- Timedelta parser -->
delta_parser = TenseParser(TenseParser.TIMEDELTA)
delta_value = delta_parser.parse(time_string)
# <-- Assertions -->
assert isinstance(delta_value, datetime.timedelta)
assert str(delta_value) == "1 day, 0:02:05"

Reconfiguring existing settings

from tense import TenseParser, from_tense_file_source

config_emulation = """
[model.Tense]
multiplier = 2  # each unit of time will be multiplied by 2
# !!! Note: If the multiplier is <= 0, then the parsers will 
# not work correctly. In this case, a warning will be sent to the console.

[units.Minute]
duration = 120  # Why not?...
aliases = my_minute, my_minutes, my_min, my_mins
"""
parser = TenseParser(
    TenseParser.TIMEDELTA,
    tenses=from_tense_file_source(config_emulation),
)
delta_value = parser.parse("1 my_min 10my_mins 9  my_minutes")
assert str(delta_value) == "1:20:00"  # (each 120 * 2)

Adding new settings

from tense import TenseParser, from_tense_file_source

config_emulation = """
[model.Tense]  # This header is required.

[virtual]
duration = exp(year * 10)
aliases = decade, dec, decs, decades
"""

parser = TenseParser(
    TenseParser.TIMEDELTA,
    tenses=from_tense_file_source(config_emulation),
)
delta_value = parser.parse("1year 10 decades5   seconds")
assert str(delta_value) == "36865 days, 0:00:05"

FAQ

But what if you need to parse a string like: "1day and 10 minutes + 5 seconds"? Let's see:

>> > from tense import TenseParser

>> > complex_string = "1day and 10 minutes + 5 seconds"

>> > parser = TenseParser(TenseParser.TIMEDELTA)
>> > parser.parse(complex_string)
'0:00:05'

Wait... What? 5 second? But there are days and minutes...

• It's okay, you're using flexible tense! This problem is solved in two ways:
  1. You write your own time_resolver and pass it
  2. Choose an existing one from tense.resolvers

Let's demonstrate! I will use the second option, since the built-in time resolvers in tense are suitable for me.

>> > from tense import TenseParser, resolvers

>> > complex_string = "1day and 10 minutes + 5 seconds"

>> > parser = TenseParser(TenseParser.TIMEDELTA, time_resolver=resolvers.smart_resolver)
>> > parser.parse(complex_string)
'1 day, 0:10:05'

Well, that's better!

tense.application.resolvers.smart_resolver() is also case insensitive!

>> > from tense import TenseParser, resolvers

>> > complex_string = "1DAY and 10 MINUTES + 5 SECONDS"

>> > parser = TenseParser(TenseParser.TIMEDELTA, time_resolver=resolvers.smart_resolver)
>> > parser.parse(complex_string)
'1 day, 0:10:05'

Examples.

If you think that this is where the possibilities of tense ends, then you are wrong! The possibilities of tense are too many for a README, so I suggest you move on to viewing the usage examples here:

Tense Examples

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

License

Distributed under the Apache 2.0 License. See LICENSE for more information.

Contact

Acknowledgments

• Choose an Open Source License
• Img Shields
• GitHub Pages
• Python
• Python Community
• MkDocs
• MkDocs Material

History

Initially, the project was made asynchronous, which significantly slowed down the parsing process, because tense is a CPU-bound module.

By refactoring the project, we got a ~x22.31 speedup in processing complex strings (using smart_resolver).

Was: ~0.00095030...μs | Now: ~0.00004260...μs

And ~x38.28 speed up processing simple strings (using basic_resolver).

Was: ~0.00062400...μs | Now: ~0.00001630...μs

The previous (async) version is still available in the repository branches - https://github.com/Animatea/tense/tree/async-final, but the site with the documentation will be changed. Note that the package on PyPi will also remain in the public domain.