aboutsummaryrefslogtreecommitdiffstats
path: root/docs/source/getting-started.rst
blob: 92264a35e7afadf81481650dd8ec451bc5bf6521 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
Getting Started
===============

Example
-------

The ``config_file`` package exposes ``ConfigFile``, ``ParsingError``,
and ``BaseParser`` to the public API.

Sample Configuration File
~~~~~~~~~~~~~~~~~~~~~~~~~

``config.ini``

.. code:: ini

   [calendar]
   today = monday
   start_week_on_sunday = false
   today_index = 0
   quarter_hours_passed = 0.25

Create a ConfigFile
~~~~~~~~~~~~~~~~~~~

.. code:: python

   from config_file import ConfigFile

   config = ConfigFile("~/.config/test/config.ini")

Output your config file as a string
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code:: python

   config.stringify()
   >>> '[calendar]\ntoday = monday\nstart_week_on_sunday = false\ntoday_index = 0\nquarter_hours_passed = 0.25\n\n'

Retrieve values or sections
~~~~~~~~~~~~~~~~~~~~~~~~~~~

A section.key format is used for retrieving and setting values.

.. code:: python

   # Values from the config file are automatically parsed
   config.get("calendar.start_week_on_sunday")
   >>> False

   # Unless you don't want them to be parsed
   config.get("calendar.start_week_on_sunday", parse_types=False)
   >>> 'false'

   config.get("calendar")
   >>> {'today': 'monday', 'start_week_on_sunday': False, 'today_index': 0, 'quarter_hours_passed': 0.25}

Set values
~~~~~~~~~~

.. code:: python

   config.set("calendar.today_index", 20)
   >>> True
   config.stringify()
   >>> '[calendar]\ntoday = monday\nstart_week_on_sunday = false\ntoday_index = 20\nquarter_hours_passed = 0.25\n\n'

   # If you specify a section that isn't in your config file, the section and the key are added for you.
   config.set("week.tuesday_index", 2)
   >>> True
   config.stringify()
   >>> '[calendar]\ntoday = monday\nstart_week_on_sunday = false\ntoday_index = 20\nquarter_hours_passed = 0.25\n\n[week]\ntuesday_index = 2\n\n'

.. _delete-sections-or-keyvalue-pairs:

Delete sections or key/value pairs.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code:: python

   config.delete('week')
   >>> True
   config.stringify()
   >>> '[calendar]\ntoday = monday\nstart_week_on_sunday = false\ntoday_index = 20\nquarter_hours_passed = 0.25\n\n'

   config.delete('calendar.today')
   >>> True
   config.stringify()
   >>> '[calendar]\nstart_week_on_sunday = false\ntoday_index = 20\nquarter_hours_passed = 0.25\n\n'

Check whether you have a particular section or key
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code:: python

   config.has('calendar')
   >>> True

   config.has('week')
   >>> False

   config.has('calendar.start_week_on_sunday')
   >>> True

Save when you're done
~~~~~~~~~~~~~~~~~~~~~

Write the contents of the file back out. ``set()`` and ``delete()`` both
modify the contents of the file and require a call to ``save()`` to
write those changes back out.

.. code:: python

   config.save()
   >>> True

Restore the file back to its original
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The current configuration file would be deleted and replaced by a copy
of the original. By default, since our passed in config file was at path
``~/.config/test/config.ini``, ``restore_original()`` will look for
``~/.config/test/config.original.ini``.

.. code:: python

   config.restore_original()
   >>> True

   # But you can also specify the original config file explicitly.
   config.restore_original(original_file_path="~/some_other_directory/this_is_actually_the_original.ini")
   >>> True

Using your own parser
---------------------

You can still use config file, even if you don't use one of our supported
configuration formats. The ``ConfigFile`` object swaps in the parser it needs
based on the file format. However, the constructor takes in an optional
parser argument that you can use to supply your own custom parser. The only
requirement is that the parser must be a concrete implementation of ``BaseParser``.