Dave Cinege Git Repo thesaurus / 197aa19
README.rst: Expanded code examples. Touched up thesauruscfg_sample. Dave Cinege 2 years ago
3 changed file(s) with 70 addition(s) and 46 deletion(s). Raw diff Collapse all Expand all
88
99 :Source code: https://git.cinege.com/thesaurus
1010 :Telegram Group: https://t.me/PythonThesaurus
11
12 The Thesaurus family works with Python 2.6+ to 3.8+.
13
14
15 About
16 ------
17 Thesaurus is a mapping data type with recursive keypath map and
18 attribute aliasing. It is a subclass of dict() and is mostly
19 compatible as a general use dictionary replacement.
20
21 Thesaurus prefers to be imported and called as thes() in the
22 same way you would use dict(). Thesaurus likes to think of itself
23 as a Python data type primative that should be used along side of
24 dict(), similar to the relationship between list() and tuple();
25 they are overlappingly similar but serve different purposes
26 and diverge to incompatibilities. Thesaurus is currently
27 content with not having it's own data type tokens. Hopefully
28 so are you.
29
30 ThesaurusExtended is a subclass of Thesaurus providing additional
31 usability methods such as recursive key and value searching.
32
33 ThesaurusCfg is a subclass of ThesaurusExtended providing a nested
34 key configuration file parser and per key data coercion methods.
1135
1236
1337 Quick Start
2246 are all about.
2347
2448
25 Quick Overview
26 --------------
49 Simple Code Examples
50 --------------------
2751
2852 .. code:: python
29
53
54 # Thesaurus Basics
3055 from thesaurus import thes, Keypath
3156 t = thes()
3257 t.set_path('a.b.c.d', 'Hello')
3358 print(t['a']['b']['c']['d']) # as nested keys
3459 print(t.a.b.c.d) # attribute aliasing
3560 print(t.a.b['c'].d) # as both
36
37 kp = Keypath('a.b.c.d') # a keypath obj
38 print(t[kp]) # keypath as the 'key'
3961 print('The value: {a.b.c.d}'.format(**t))
4062 print(f'The value: {t.a.b.c.d}') # py3.6+ f-string. perfection!
63
64 kp = Keypath('a.b.c.d') # a keypath object
65 print(t[kp]) # keypath as recursive map
4166
4267 >>> 'a.b.c.d' in t # recursive contains
4368 True
4772 'a.b.c.d'
4873 >>> print(repr(kp))
4974 ['a', 'b', 'c', 'd'] # but it's really like a list
50
51
52 cfgs = '''
75
76 # ThesaurusExtended
77 from thesaurus import thesext
78 te = thesext()
79 te.set_path('a.b.c.d', 'Hello')
80 print(te.a.b.c[0]) # as numeric index or slice
81 for kp in te.get_keys('Hello'): # a list of matching keypath's is returned
82 print('Parent key:', kp[-1])
83
84 # ThesaurusCfg
85 from thesauruscfg import thescfg
86 cfg = thescfg()
87 s = '''
5388 prog.version(static_int) = 123
5489 opt.verbose (str_to_bool) = yes
5590 hi = Hello
56 '''
57 from thesauruscfg import thescfg
58 cfg = thescfg()
59 >>> cfg.parse(cfgs)
91 '''
92 # coercion methods can intercept parse, dump, and setitem
93 >>> cfg.parse(s)
6094 {'prog': {'version': 123}, 'opt': {'verbose': True}, 'hi': 'Hello'}
61
95 >>> cfg.dump()
96 'prog.version = 123\nopt.verbose = True\nhi = Hello\n'
97 >>> cfg.prog.version = '123214' # static_int coercion method
98 >>> cfg.prog.version # won't allow value change
99 123
100
62101 import json
63102 >>> print(json.dumps(cfg, indent=4, separators=(',', ': ')))
64103 {
72111 }
73112
74113
75 About
76 ------
77 Thesaurus is a mapping data type with key recursion and attribute
78 aliasing. It is a subclass of dict() and compatible as a dictionary
79 replacement baring where key path recursion may take place.
80
81 Thesaurus prefers to be imported and called as thes() in the
82 same way you would use dict(). Thesaurus likes to think of itself
83 as a Python data type primative that should be used along side of
84 dict(), similar to the relationship between list() and tuple();
85 they are overlappingly similar but serve different purposes
86 and diverge to incompatibilities. Thesaurus is currently
87 content with not having it's own data type tokens. Hopefully
88 so are you.
89
90 ThesaurusExtended is a subclass of Thesaurus providing additional
91 usability methods such as recursive key and value searching.
92
93 ThesaurusCfg is a subclass of ThesaurusExtended providing a configuration
94 file parser and per key data coercion methods.
95
96 The Thesaurus family works with Python 2.6+ to 3.8+.
97
98
99114 Currect State of Code - 2019-11-13
100115 ----------------------------------
101116 Thesaurus first came about in December 2012. It has gone through a total of
104119 something I've been wishing I've had to use for myself for at least the
105120 last 4 years.
106121
107 The current version you will find here has recently had the recent addition
122 The current version you will find here has had the recent addition
108123 of Keypaths and while it is quite usable might still have a few bugs to
109124 iron out.
110125
111126 Additonally parts should be cleaned and reimplemented now that Keypath's
112127 have been implemented. If you are reviewing the code, this will likely
113128 stand out. With that said, please remember that at this stage few things
114 have been done by accident. There are certainly section that can be cleaned
129 have been done by accident. There are certainly sections that can be cleaned
115130 for readablity, however they are this way, on purpose, for performance.
116131
117132 ThesaurusCfg is quite new. It works. I have a version of it frozen in
124139
125140 - Finalize name conventions. Use set_path() or setpath()?
126141
127 - Finalize specialtiy method names, Are merge(), mesh() and
142 - Finalize specialtiy method names. Are merge(), mesh() and
128143 screen() good names that make sense? I am struggling with the
129 ThesaurusExtended method names myself.
144 ThesaurusExtended search method names myself.
130145
131146 - Review how I do recursive copy/deepcopys.
132147
133148 - Decide how to properly handle copying ThesaurusCfg coercion methods.
134149
135 - Resolve Thesaurus's schizophrenia.
150 - Resolve Thesaurus's schizophrenia:
136151
137152 .. code:: python
138153
154 t = thes()
155 t.set_path('a.b.c', 'Hi')
139156 v = t['a.b.c'] # This recurses
140 t['a.b.c'] = v # This does not, needs set_path().
157 t['a.b.c'] = 'Bye' # This set a dotted keyname
158 v = t['a.b.c'] # v == 'Bye', not 'Hi'
159 >>> t
160 {'a': {'b': {'c': 'Hello'}}, 'a.b.c': 'Bye'}
161
162
141163
142164 I want to be comfortable this feels natural to others or find a
143165 better way.
7272
7373 # Simple key values using coercion methods
7474 abc (static_int) = 123
75 a.bc (static_int) = 456
7675 xyz (int) = 678
7776 myitemlist (str_list) = "Item 1's" "'Item_2'" "Item 3" "Item_4"
7877 mybool (str_to_bool) = yes
7978
8079 # Keypath and value
80 a.bc (static_int) = 456
8181 program.name = thesauruscfg_sample.py
8282
8383 # keypath and multi-line value
3434
3535 # mesh in the default.gateways values (don't overwrite existing)
3636 # FIX ME not yet copying the coercion methods
37 for t in cfg.networks.values():
37 for k,t in cfg.networks.items():
38 print('mesh: cfg.networks.{0}.gateways'.format(k))
3839 t.gateways.mesh(cfg.defaults.gateways)
40 print('---\n')
3941
4042 print('cfg.dump()\n---')
4143 print(cfg.dump())