Skip to content

Commit 9aab459

Browse files
ttafsirttafsir
authored
improve examples in readme and plugin docs
Release/1.2.1
2 parents da27160 + af00ab0 commit 9aab459

File tree

4 files changed

+256
-17
lines changed

4 files changed

+256
-17
lines changed

‎README.md‎

Lines changed: 41 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -11,23 +11,53 @@ A collection of Ansible plugins to manage SQLite databases leveraging the `sqlit
1111
- `sqlite-utils` package
1212

1313

14-
You can install the collection from Ansible Galaxy:
14+
## Collection contents
15+
16+
### Plugins
17+
18+
#### Lookup Plugins
19+
20+
* `ttafsir.sqlite_utils.sqlite`: A lookup plugin that returns query results from a sqlite database using the `rows_where` method.
1521

16-
```bash
17-
ansible-galaxy collection install ttafsir.sqlite_utils
18-
```
1922

20-
### From Source
23+
## Usage Examples
2124

22-
Clone the repository from GitHub:
25+
### Lookup
2326

24-
```bash
25-
git clone https://github.com/ttafsir/ansible-collection-sqlite-utils.git
26-
cd ansible-sqlite-utils
27-
ansible-galaxy collection build
28-
ansible-galaxy collection install ./ttafsir-sqlite_utils-*.tar.gz
27+
```yaml
28+
---
29+
- hosts: localhost
30+
gather_facts: no
31+
vars:
32+
where_arg: {"subject": "Peek #4"}
33+
34+
tasks:
35+
36+
- name: Fetch two columns from SQLite
37+
debug:
38+
msg: "{{
39+
lookup(
40+
'ttafsir.sqlite_utils.sqlite',
41+
table='emails',
42+
db_path=database,
43+
select='email_id, subject')
44+
}}"
45+
46+
- name: Fetch row from SQLite where email subject matches
47+
debug:
48+
msg: "{{
49+
lookup(
50+
'ttafsir.sqlite_utils.sqlite',
51+
table='emails',
52+
db_path='database.sqlite',
53+
where='subject = :subject',
54+
where_args=where_arg
55+
)
56+
}}"
2957
```
3058
59+
See the lookup plugin documentation for more details.
60+
3161
## License
3262
3363
This project is licensed under the MIT License. See the [LICENSE](https://github.com/ttafsir/ansible-collection-sqlite-utils/blob/main/LICENSE) file for details.

‎galaxy.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
namespace: ttafsir
33
name: sqlite_utils
4-
version: "1.2.0"
4+
version: "1.2.1"
55
readme: README.md
66

77
authors:

‎plugins/lookup/sqlite.py‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -45,24 +45,24 @@
4545
EXAMPLES = r"""
4646
- name: Fetch all rows from SQLite
4747
debug:
48-
msg: "{{ lookup('sqlite', table='emails', db_path='database.db') }}"
48+
msg: "{{ lookup('ttafsir.sqlite_utils.sqlite', table='emails', db_path='database.db') }}"
4949
5050
- name: Fetch single column from SQLite
5151
debug:
52-
msg: "{{ lookup('sqlite', table='emails', db_path='database.db', select='email_id') }}"
52+
msg: "{{ lookup('ttafsir.sqlite_utils.sqlite', table='emails', db_path='database.db', select='email_id') }}"
5353
5454
- name: Fetch two columns from SQLite
5555
debug:
56-
msg: "{{ lookup('sqlite', table='emails', db_path='database.db', select='email_id, subject') }}"
56+
msg: "{{ lookup('ttafsir.sqlite_utils.sqlite', table='emails', db_path='database.db', select='email_id, subject') }}"
5757
5858
- name: Fetch single row using a WHERE clause
5959
debug:
60-
msg: "{{ lookup('sqlite', table='emails', db_path='database.db', where='subject = :subject', where_args={'subject': 'Peek #4'}) }}"
60+
msg: "{{ lookup('ttafsir.sqlite_utils.sqlite', table='emails', db_path='database.db', where='subject = :subject', where_args={'subject': 'Peek #4'}) }}"
6161
6262
- name: Loop through all rows and display a specific column
6363
debug:
6464
msg: "{{ item.subject }}"
65-
loop: "{{ lookup('sqlite', table='emails', db_path='database.db') }}"
65+
loop: "{{ lookup('ttafsir.sqlite_utils.sqlite', table='emails', db_path='database.db') }}"
6666
"""
6767
from ansible.errors import AnsibleError
6868
from ansible.plugins.lookup import LookupBase

‎tests/NOTICE‎

Lines changed: 209 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,209 @@
1+
ansible_sqlite_utils
2+
Copyright 2023 Tafsir Thiam
3+
4+
5+
This product uses 'sqlite-utils' (https://github.com/simonw/sqlite-utils),
6+
which is licensed under the Apache 2.0 license.
7+
8+
9+
Apache License
10+
Version 2.0, January 2004
11+
http://www.apache.org/licenses/
12+
13+
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
14+
15+
1. Definitions.
16+
17+
"License" shall mean the terms and conditions for use, reproduction,
18+
and distribution as defined by Sections 1 through 9 of this document.
19+
20+
"Licensor" shall mean the copyright owner or entity authorized by
21+
the copyright owner that is granting the License.
22+
23+
"Legal Entity" shall mean the union of the acting entity and all
24+
other entities that control, are controlled by, or are under common
25+
control with that entity. For the purposes of this definition,
26+
"control" means (i) the power, direct or indirect, to cause the
27+
direction or management of such entity, whether by contract or
28+
otherwise, or (ii) ownership of fifty percent (50%) or more of the
29+
outstanding shares, or (iii) beneficial ownership of such entity.
30+
31+
"You" (or "Your") shall mean an individual or Legal Entity
32+
exercising permissions granted by this License.
33+
34+
"Source" form shall mean the preferred form for making modifications,
35+
including but not limited to software source code, documentation
36+
source, and configuration files.
37+
38+
"Object" form shall mean any form resulting from mechanical
39+
transformation or translation of a Source form, including but
40+
not limited to compiled object code, generated documentation,
41+
and conversions to other media types.
42+
43+
"Work" shall mean the work of authorship, whether in Source or
44+
Object form, made available under the License, as indicated by a
45+
copyright notice that is included in or attached to the work
46+
(an example is provided in the Appendix below).
47+
48+
"Derivative Works" shall mean any work, whether in Source or Object
49+
form, that is based on (or derived from) the Work and for which the
50+
editorial revisions, annotations, elaborations, or other modifications
51+
represent, as a whole, an original work of authorship. For the purposes
52+
of this License, Derivative Works shall not include works that remain
53+
separable from, or merely link (or bind by name) to the interfaces of,
54+
the Work and Derivative Works thereof.
55+
56+
"Contribution" shall mean any work of authorship, including
57+
the original version of the Work and any modifications or additions
58+
to that Work or Derivative Works thereof, that is intentionally
59+
submitted to Licensor for inclusion in the Work by the copyright owner
60+
or by an individual or Legal Entity authorized to submit on behalf of
61+
the copyright owner. For the purposes of this definition, "submitted"
62+
means any form of electronic, verbal, or written communication sent
63+
to the Licensor or its representatives, including but not limited to
64+
communication on electronic mailing lists, source code control systems,
65+
and issue tracking systems that are managed by, or on behalf of, the
66+
Licensor for the purpose of discussing and improving the Work, but
67+
excluding communication that is conspicuously marked or otherwise
68+
designated in writing by the copyright owner as "Not a Contribution."
69+
70+
"Contributor" shall mean Licensor and any individual or Legal Entity
71+
on behalf of whom a Contribution has been received by Licensor and
72+
subsequently incorporated within the Work.
73+
74+
2. Grant of Copyright License. Subject to the terms and conditions of
75+
this License, each Contributor hereby grants to You a perpetual,
76+
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
77+
copyright license to reproduce, prepare Derivative Works of,
78+
publicly display, publicly perform, sublicense, and distribute the
79+
Work and such Derivative Works in Source or Object form.
80+
81+
3. Grant of Patent License. Subject to the terms and conditions of
82+
this License, each Contributor hereby grants to You a perpetual,
83+
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
84+
(except as stated in this section) patent license to make, have made,
85+
use, offer to sell, sell, import, and otherwise transfer the Work,
86+
where such license applies only to those patent claims licensable
87+
by such Contributor that are necessarily infringed by their
88+
Contribution(s) alone or by combination of their Contribution(s)
89+
with the Work to which such Contribution(s) was submitted. If You
90+
institute patent litigation against any entity (including a
91+
cross-claim or counterclaim in a lawsuit) alleging that the Work
92+
or a Contribution incorporated within the Work constitutes direct
93+
or contributory patent infringement, then any patent licenses
94+
granted to You under this License for that Work shall terminate
95+
as of the date such litigation is filed.
96+
97+
4. Redistribution. You may reproduce and distribute copies of the
98+
Work or Derivative Works thereof in any medium, with or without
99+
modifications, and in Source or Object form, provided that You
100+
meet the following conditions:
101+
102+
(a) You must give any other recipients of the Work or
103+
Derivative Works a copy of this License; and
104+
105+
(b) You must cause any modified files to carry prominent notices
106+
stating that You changed the files; and
107+
108+
(c) You must retain, in the Source form of any Derivative Works
109+
that You distribute, all copyright, patent, trademark, and
110+
attribution notices from the Source form of the Work,
111+
excluding those notices that do not pertain to any part of
112+
the Derivative Works; and
113+
114+
(d) If the Work includes a "NOTICE" text file as part of its
115+
distribution, then any Derivative Works that You distribute must
116+
include a readable copy of the attribution notices contained
117+
within such NOTICE file, excluding those notices that do not
118+
pertain to any part of the Derivative Works, in at least one
119+
of the following places: within a NOTICE text file distributed
120+
as part of the Derivative Works; within the Source form or
121+
documentation, if provided along with the Derivative Works; or,
122+
within a display generated by the Derivative Works, if and
123+
wherever such third-party notices normally appear. The contents
124+
of the NOTICE file are for informational purposes only and
125+
do not modify the License. You may add Your own attribution
126+
notices within Derivative Works that You distribute, alongside
127+
or as an addendum to the NOTICE text from the Work, provided
128+
that such additional attribution notices cannot be construed
129+
as modifying the License.
130+
131+
You may add Your own copyright statement to Your modifications and
132+
may provide additional or different license terms and conditions
133+
for use, reproduction, or distribution of Your modifications, or
134+
for any such Derivative Works as a whole, provided Your use,
135+
reproduction, and distribution of the Work otherwise complies with
136+
the conditions stated in this License.
137+
138+
5. Submission of Contributions. Unless You explicitly state otherwise,
139+
any Contribution intentionally submitted for inclusion in the Work
140+
by You to the Licensor shall be under the terms and conditions of
141+
this License, without any additional terms or conditions.
142+
Notwithstanding the above, nothing herein shall supersede or modify
143+
the terms of any separate license agreement you may have executed
144+
with Licensor regarding such Contributions.
145+
146+
6. Trademarks. This License does not grant permission to use the trade
147+
names, trademarks, service marks, or product names of the Licensor,
148+
except as required for reasonable and customary use in describing the
149+
origin of the Work and reproducing the content of the NOTICE file.
150+
151+
7. Disclaimer of Warranty. Unless required by applicable law or
152+
agreed to in writing, Licensor provides the Work (and each
153+
Contributor provides its Contributions) on an "AS IS" BASIS,
154+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
155+
implied, including, without limitation, any warranties or conditions
156+
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
157+
PARTICULAR PURPOSE. You are solely responsible for determining the
158+
appropriateness of using or redistributing the Work and assume any
159+
risks associated with Your exercise of permissions under this License.
160+
161+
8. Limitation of Liability. In no event and under no legal theory,
162+
whether in tort (including negligence), contract, or otherwise,
163+
unless required by applicable law (such as deliberate and grossly
164+
negligent acts) or agreed to in writing, shall any Contributor be
165+
liable to You for damages, including any direct, indirect, special,
166+
incidental, or consequential damages of any character arising as a
167+
result of this License or out of the use or inability to use the
168+
Work (including but not limited to damages for loss of goodwill,
169+
work stoppage, computer failure or malfunction, or any and all
170+
other commercial damages or losses), even if such Contributor
171+
has been advised of the possibility of such damages.
172+
173+
9. Accepting Warranty or Additional Liability. While redistributing
174+
the Work or Derivative Works thereof, You may choose to offer,
175+
and charge a fee for, acceptance of support, warranty, indemnity,
176+
or other liability obligations and/or rights consistent with this
177+
License. However, in accepting such obligations, You may act only
178+
on Your own behalf and on Your sole responsibility, not on behalf
179+
of any other Contributor, and only if You agree to indemnify,
180+
defend, and hold each Contributor harmless for any liability
181+
incurred by, or claims asserted against, such Contributor by reason
182+
of your accepting any such warranty or additional liability.
183+
184+
END OF TERMS AND CONDITIONS
185+
186+
APPENDIX: How to apply the Apache License to your work.
187+
188+
To apply the Apache License to your work, attach the following
189+
boilerplate notice, with the fields enclosed by brackets "[]"
190+
replaced with your own identifying information. (Don't include
191+
the brackets!) The text should be enclosed in the appropriate
192+
comment syntax for the file format. We also recommend that a
193+
file or class name and description of purpose be included on the
194+
same "printed page" as the copyright notice for easier
195+
identification within third-party archives.
196+
197+
Copyright [yyyy] [name of copyright owner]
198+
199+
Licensed under the Apache License, Version 2.0 (the "License");
200+
you may not use this file except in compliance with the License.
201+
You may obtain a copy of the License at
202+
203+
http://www.apache.org/licenses/LICENSE-2.0
204+
205+
Unless required by applicable law or agreed to in writing, software
206+
distributed under the License is distributed on an "AS IS" BASIS,
207+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
208+
See the License for the specific language governing permissions and
209+
limitations under the License.

0 commit comments

Comments
 (0)