From 2b1f151f61b815b916b245f1ceb47a242f6346c8 Mon Sep 17 00:00:00 2001 From: EpocDotFr Date: Tue, 17 Jan 2017 13:02:52 +0100 Subject: [PATCH] Docs done --- docs/index.rst | 255 +++++++++++++++++++++---------------------------- todotxtio.py | 16 ++-- 2 files changed, 119 insertions(+), 152 deletions(-) diff --git a/docs/index.rst b/docs/index.rst index 9c35882..cae9aa1 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -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 ********************* diff --git a/todotxtio.py b/todotxtio.py index 9f127a9..603d99e 100644 --- a/todotxtio.py +++ b/todotxtio.py @@ -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 @@ -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.