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

Commit

Permalink
Docs done
Browse files Browse the repository at this point in the history
  • Loading branch information
@EpocDotFr
EpocDotFr committed Jan 17, 2017
1 parent 7d8e850 commit 2b1f151
Show file tree
Hide file tree
Showing 2 changed files with 119 additions and 152 deletions.
255 changes: 111 additions & 144 deletions docs/index.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -46,212 +46,179 @@ The functions below all return a plain-old Python list filled with :class:`todot
# Or: list_of_todos = todotxtio.from_stream(stream_full_of_todos)
# Or: list_of_todos = todotxtio.from_dicts(list_of_todos_dict)
Manipulating todos
******************
The :class:`todotxtio.Todo` class
*********************************

#### Basics
Basics
''''''

Create a new todo by instantiating a `Todo` object. You can feed todo data via its constructor arguments (none are required):
Create a new todo by instantiating a :class:`todotxtio.Todo` object. You can feed todo data via its constructor arguments (none are required):

```python
todo = todotxtio.Todo(
text='Thank Guido for such an awesome programming language',
priority='A',
creation_date='2016-11-20'
)
print(todo) # (A) 2016-11-20 Thank Guido for such an awesome programming language
```

Or you also can instantiate an empty (or partially-instantiated) `Todo` object and define its parameters later:

```python
todo = todotxtio.Todo(
creation_date='2016-11-20' # For example only, but constructor can be empty and this can be defined later as well
)
todo.text = 'Thank Guido for such an awesome programming language'
todo.priority = 'A'
.. code-block:: python
print(todo) # (A) 2016-11-20 Thank Guido for such an awesome programming language
```
todo = todotxtio.Todo(
text='Thank Guido for such an awesome programming language',
priority='A',
creation_date='2016-11-20'
)
Once a `Todo` is instantiated, you can use its attributes to modify its data.
print(todo) # (A) 2016-11-20 Thank Guido for such an awesome programming language
```python
# todo is a Todo instance
Or you also can instantiate an empty (or partially-instantiated) :class:`todotxtio.Todo` object and define its parameters later:

todo.text = 'Hello, I\'m the new text'
todo.priority = 'C'
todo.creation_date = None # Deleting the creation date
```
.. code-block:: python
Playing with todo lists is easy, the same way when manipulating any Python lists:
todo = todotxtio.Todo(
creation_date='2016-11-20' # For example only, but constructor can be empty and this can be defined later as well
)
```python
todos = []
todo.text = 'Thank Guido for such an awesome programming language'
todo.priority = 'A'
todos.append(todotxtio.Todo(text='A todo in its simplest form!'))
print(todo) # (A) 2016-11-20 Thank Guido for such an awesome programming language
# Updating the completion of the first todo in the todo list (plain Python syntax)
todos[0].completed = True
Once a :class:`todotxtio.Todo` is instantiated, you can use its attributes to modify its data.

# Adding a new todo
todos.append(todotxtio.Todo(text='A second todo in its simplest form!'))
.. code-block:: python
# Remove a todo
del todos[0]
```
# todo is a Todo instance
#### Todo dicts
todo.text = 'Hello, I\'m the new text'
todo.priority = 'C'
todo.creation_date = None # Deleting the creation date
You can export a `Todo` to a Python dict. Keys and values are exactly the same as the `Todo` constructor:
Playing with todo lists is easy, the same way when manipulating any Python lists:

```python
# todo is a Todo instance
.. code-block:: python
todo_dict = todo.to_dict()
```
todos = []
And vice-versa, you can instantiate a `Todo` object from a dict using the standard Python way:
todos.append(todotxtio.Todo(text='A todo in its simplest form!'))
```python
todo_dict = {
'text': 'Hey ho!',
'completed': True,
'priority': 'D',
'projects': ['blah']
}
# Updating the completion of the first todo in the todo list (plain Python syntax)
todos[0].completed = True
todo = todotxtio.Todo(**todo_dict)
```
# Adding a new todo
todos.append(todotxtio.Todo(text='A second todo in its simplest form!'))
#### Projects and contexts
# Remove a todo
del todos[0]
They are both plain-old Python lists without leadings `+` and `@`:
Todo dicts
''''''''''

```python
todo = todotxtio.Todo(
text='Thank Guido for such an awesome programming language',
priority='A',
creation_date='2016-11-20'
)
You can export a :class:`todotxtio.Todo` to a Python dict. Keys and values are exactly the same as the :class:`todotxtio.Todo` constructor:

# Define some projects and contexts
todo.projects = ['python']
todo.contexts = ['awesomeness', 'ftw']
.. code-block:: python
# Append to existings projects or contexts
todo.projects.append('awesome-project')
todo.contexts.append('cool')
# todo is a Todo instance
# Remove a context
todo.contexts.remove('cool')
todo_dict = todo.to_dict()
# Empty the projects list
todo.projects = [] # Or None
And vice-versa, you can instantiate a :class:`todotxtio.Todo` object from a dict using the standard Python way:

print(todo) # (A) 2016-11-20 Thank Guido for such an awesome programming language @awesomeness @ftw
```
.. code-block:: python
#### Todo completion
todo_dict = {
'text': 'Hey ho!',
'completed': True,
'priority': 'D',
'projects': ['blah']
}
You can either mark a todo as completed by setting its `completed` attribute to `True`:
todo = todotxtio.Todo(**todo_dict)
```python
todo = todotxtio.Todo(
text='Thank Guido for such an awesome programming language',
priority='A',
creation_date='2016-11-20'
)
Projects and contexts
'''''''''''''''''''''

todo.completed = True
They are both plain-old Python lists without leadings ``+`` and ``@``:

print(todo) # x (A) 2016-11-20 Thank Guido for such an awesome programming language
```
.. code-block:: python
Or by defining its completion date, which automatically set its `completed` attribute to `True`:
todo = todotxtio.Todo(
text='Thank Guido for such an awesome programming language',
priority='A',
creation_date='2016-11-20'
)
```python
todo = todotxtio.Todo(
text='Thank Guido for such an awesome programming language',
priority='A',
creation_date='2016-11-20'
)
# Define some projects and contexts
todo.projects = ['python']
todo.contexts = ['awesomeness', 'ftw']
todo.completion_date = '2016-12-01'
# Append to existings projects or contexts
todo.projects.append('awesome-project')
todo.contexts.append('cool')
print(todo) # x 2016-12-01 (A) 2016-11-20 Thank Guido for such an awesome programming language
```
# Remove a context
todo.contexts.remove('cool')
This is also applicable to the `Todo` constructor.
# Empty the projects list
todo.projects = [] # Or None
Of course, inverse is also applicable (setting `completed` to `False` removes the completion date).
print(todo) # (A) 2016-11-20 Thank Guido for such an awesome programming language @awesomeness @ftw
#### Tags
Todo completion
'''''''''''''''

Tags, also called add-ons metadata, are represented by a simple one-dimension dictionary. They allow you to easily
define and retrieve custom formatted data:
You can either mark a todo as completed by setting its ``completed`` attribute to ``True``:

```python
todo = todotxtio.Todo(
text='Thank Guido for such an awesome programming language'
)
.. code-block:: python
todo.tags = { # Define some tags
'key': 'value',
'second': 'tag'
}
todo = todotxtio.Todo(
text='Thank Guido for such an awesome programming language',
priority='A',
creation_date='2016-11-20'
)
todo.tags['due'] = '2016-12-01'
todo.completed = True
# Remove a tag
del todo.tags['second']
print(todo) # x (A) 2016-11-20 Thank Guido for such an awesome programming language
print(todo) # Thank Guido for such an awesome programming language key:value due:2016-12-01
Or by defining its completion date, which automatically set its ``completed`` attribute to ``True``:

# Empty tags
todo.tags = {} # Or None
```
.. code-block:: python
### Writing
todo = todotxtio.Todo(
text='Thank Guido for such an awesome programming language',
priority='A',
creation_date='2016-11-20'
)
At some point you'll need to save your todo list.
todo.completion_date = '2016-12-01'
**Writing to a file:**
print(todo) # x 2016-12-01 (A) 2016-11-20 Thank Guido for such an awesome programming language
```python
# todos is a list of Todo objects
This is also applicable to the :class:`todotxtio.Todo` constructor.

todotxtio.to_file('todo.txt', todos, encoding='utf-8') # utf-8 is the default
```
Of course, inverse is also applicable (setting ``completed`` to ``False`` removes the completion date).

**Caution:** This will overwrite the whole file. Also, data will be UTF-8 encoded.
Tags
''''

**Export all todos to string:**
Tags, also called add-ons metadata, are represented by a simple one-dimension dictionary. They allow you to easily
define and retrieve custom formatted data:

```python
# todos is a list of Todo objects
.. code-block:: python
string_full_of_todos = todotxtio.to_string(todos)
```
todo = todotxtio.Todo(
text='Thank Guido for such an awesome programming language'
)
**Writing to an already-opened stream:**
todo.tags = { # Define some tags
'key': 'value',
'second': 'tag'
}
```python
# todos is a list of Todo objects
# stream is an already-opened stream
todo.tags['due'] = '2016-12-01'
todotxtio.to_stream(stream, todos, close=False) # Will not close the stream
```
# Remove a tag
del todo.tags['second']
**Convert to a list of todo dicts (e.g to serialize them to JSON):**
print(todo) # Thank Guido for such an awesome programming language key:value due:2016-12-01
```python
# todos is a list of Todo objects
# Empty tags
todo.tags = {} # Or None
todo_dicts = todotxtio.to_dicts(todos)
```
Searching a todo list
*********************
Expand Down
16 changes: 8 additions & 8 deletions todotxtio.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -168,13 +168,13 @@ class Todo:
"""Represent one todo.
:param str text: The text of the todo
:param bool completed: Should this todo be marked as completed or not (default to False)
:param str completion_date: A completion date, in the YYYY-MM-DD format. Setting this property will automatically set completed to True (default to None)
:param str priority: The priority of the todo represented by a char bewteen A-Z (default to None)
:param str creation_date: A create date, in the YYYY-MM-DD format (default to None)
:param list projects: A list of projects without + (default to an empty list)
:param list contexts: A list of projects without @ (default to an empty list)
:param dict tags: A dict of tags (default to an empty dict)
:param bool completed: Should this todo be marked as completed or not
:param str completion_date: A completion date, in the YYYY-MM-DD format. Setting this property will automatically set completed to True
:param str priority: The priority of the todo represented by a char between A-Z
:param str creation_date: A create date, in the YYYY-MM-DD format
:param list projects: A list of projects without +
:param list contexts: A list of projects without @
:param dict tags: A dict of tags
"""
text = None
completed = False
Expand Down Expand Up @@ -276,7 +276,7 @@ def search(todos, text=None, completed=None, completion_date=None, priority=None
"""Return a list of todos that matches the provided filters.
It takes the exact same parameters as the :class:`todotxtio.Todo` object constructor, and return a list of :class:`todotxtio.Todo` objects as well.
All criteria defaults to `None` which means that the criteria is ignored.
All criteria defaults to ``None`` which means that the criteria is ignored.
A todo will be returned in the results list if all of the criteria matches. From the moment when a todo is sent in the results list, it will
never be checked again.
Expand Down

0 comments on commit 2b1f151

Please sign in to comment.