Skip to content

Commit 3455420

Browse files
lgarber-akamailgarber-akamai
authored
doc: Improve filtering documentation (#301)
## 📝 Description This change makes various improvements to the documentation relevant to filtering in this repository. This includes correcting broken links, adding an import example, and linking from filter params to the filtering guide. Resolves #217
1 parent 83e8269 commit 3455420

19 files changed

Lines changed: 93 additions & 11 deletions

‎docs/guides/core_concepts.rst‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -49,12 +49,13 @@ certain group. This library implements filtering with a SQLAlchemy-like
4949
syntax, where a model's attributes may be used in comparisons to generate
5050
filters. For example::
5151

52+
from linode_api4 import Instance
53+
5254
prod_linodes = client.linode.instances(Instance.group == "production")
5355

5456
Filters may be combined using boolean operators similar to SQLAlchemy::
5557

5658
# and_ and or_ can be imported from the linode package to combine filters
57-
from linode_api4 import or_
5859
prod_or_staging = client.linode.instances(or_(Instance.group == "production",
5960
Instance.group == "staging"))
6061

@@ -66,7 +67,7 @@ Filters may be combined using boolean operators similar to SQLAlchemy::
6667
Filters are generally only applicable for the type of model you are querying,
6768
but can be combined to your heart's content. For numeric fields, the standard
6869
numeric comparisons are accepted, and work as you'd expect. See
69-
:doc:`Filtering Collections<../linode/objects/filtering>` for full details.
70+
:doc:`Filtering Collections</linode_api4/objects/filtering>` for full details.
7071

7172
Models
7273
------

‎linode_api4/groups/account.py‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -49,6 +49,8 @@ def events(self, *filters):
4949
API Documentation: https://www.linode.com/docs/api/account/#events-list
5050
5151
:param filters: Any number of filters to apply to this query.
52+
See :doc:`Filtering Collections</linode_api4/objects/filtering>`
53+
for more details on filtering.
5254
5355
:returns: A list of events on the current account matching the given filters.
5456
:rtype: PaginatedList of Event
@@ -124,6 +126,8 @@ def oauth_clients(self, *filters):
124126
API Documentation: https://www.linode.com/docs/api/account/#oauth-clients-list
125127
126128
:param filters: Any number of filters to apply to this query.
129+
See :doc:`Filtering Collections</linode_api4/objects/filtering>`
130+
for more details on filtering.
127131
128132
:returns: A list of OAuth Clients associated with this account.
129133
:rtype: PaginatedList of OAuthClient
@@ -167,6 +171,8 @@ def users(self, *filters):
167171
API Documentation: https://www.linode.com/docs/api/account/#users-list
168172
169173
:param filters: Any number of filters to apply to this query.
174+
See :doc:`Filtering Collections</linode_api4/objects/filtering>`
175+
for more details on filtering.
170176
171177
:returns: A list of users on this account.
172178
:rtype: PaginatedList of User

‎linode_api4/groups/database.py‎

Lines changed: 12 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -33,7 +33,9 @@ def types(self, *filters):
3333
3434
API Documentation: https://www.linode.com/docs/api/databases/#managed-database-types-list
3535
36-
:param filters: Any number of filters to apply to the query.
36+
:param filters: Any number of filters to apply to this query.
37+
See :doc:`Filtering Collections</linode_api4/objects/filtering>`
38+
for more details on filtering.
3739
3840
:returns: A list of types that match the query.
3941
:rtype: PaginatedList of DatabaseType
@@ -51,7 +53,9 @@ def engines(self, *filters):
5153
5254
API Documentation: https://www.linode.com/docs/api/databases/#managed-database-engines-list
5355
54-
:param filters: Any number of filters to apply to the query.
56+
:param filters: Any number of filters to apply to this query.
57+
See :doc:`Filtering Collections</linode_api4/objects/filtering>`
58+
for more details on filtering.
5559
5660
:returns: A list of types that match the query.
5761
:rtype: PaginatedList of DatabaseEngine
@@ -65,6 +69,8 @@ def instances(self, *filters):
6569
API Documentation: https://www.linode.com/docs/api/databases/#managed-databases-list-all
6670
6771
:param filters: Any number of filters to apply to this query.
72+
See :doc:`Filtering Collections</linode_api4/objects/filtering>`
73+
for more details on filtering.
6874
6975
:returns: A list of databases that matched the query.
7076
:rtype: PaginatedList of Database
@@ -78,6 +84,8 @@ def mysql_instances(self, *filters):
7884
API Documentation: https://www.linode.com/docs/api/databases/#managed-mysql-databases-list
7985
8086
:param filters: Any number of filters to apply to this query.
87+
See :doc:`Filtering Collections</linode_api4/objects/filtering>`
88+
for more details on filtering.
8189
8290
:returns: A list of MySQL databases that matched the query.
8391
:rtype: PaginatedList of MySQLDatabase
@@ -141,6 +149,8 @@ def postgresql_instances(self, *filters):
141149
API Documentation: https://www.linode.com/docs/api/databases/#managed-postgresql-databases-list
142150
143151
:param filters: Any number of filters to apply to this query.
152+
See :doc:`Filtering Collections</linode_api4/objects/filtering>`
153+
for more details on filtering.
144154
145155
:returns: A list of PostgreSQL databases that matched the query.
146156
:rtype: PaginatedList of PostgreSQLDatabase

‎linode_api4/groups/domain.py‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,8 @@ def __call__(self, *filters):
1616
API Documentation: https://www.linode.com/docs/api/domains/#domains-list
1717
1818
:param filters: Any number of filters to apply to this query.
19+
See :doc:`Filtering Collections</linode_api4/objects/filtering>`
20+
for more details on filtering.
1921
2022
:returns: A list of Domains the acting user can access.
2123
:rtype: PaginatedList of Domain

‎linode_api4/groups/image.py‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,9 @@ def __call__(self, *filters):
2020
2121
API Documentation: https://www.linode.com/docs/api/images/#images-list
2222
23-
:param filters: Any number of filters to apply to the query.
23+
:param filters: Any number of filters to apply to this query.
24+
See :doc:`Filtering Collections</linode_api4/objects/filtering>`
25+
for more details on filtering.
2426
2527
:returns: A list of available Images.
2628
:rtype: PaginatedList of Image

‎linode_api4/groups/linode.py‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -41,7 +41,9 @@ def types(self, *filters):
4141
4242
API documentation: https://www.linode.com/docs/api/linode-types/#types-list
4343
44-
:param filters: Any number of filters to apply to the query.
44+
:param filters: Any number of filters to apply to this query.
45+
See :doc:`Filtering Collections</linode_api4/objects/filtering>`
46+
for more details on filtering.
4547
4648
:returns: A list of types that match the query.
4749
:rtype: PaginatedList of Type
@@ -58,6 +60,8 @@ def instances(self, *filters):
5860
API Documentation: https://www.linode.com/docs/api/linode-instances/#linodes-list
5961
6062
:param filters: Any number of filters to apply to this query.
63+
See :doc:`Filtering Collections</linode_api4/objects/filtering>`
64+
for more details on filtering.
6165
6266
:returns: A list of Instances that matched the query.
6367
:rtype: PaginatedList of Instance
@@ -76,6 +80,8 @@ def stackscripts(self, *filters, **kwargs):
7680
API Documentation: https://www.linode.com/docs/api/stackscripts/#stackscripts-list
7781
7882
:param filters: Any number of filters to apply to this query.
83+
See :doc:`Filtering Collections</linode_api4/objects/filtering>`
84+
for more details on filtering.
7985
:param mine_only: If True, returns only private StackScripts
8086
:type mine_only: bool
8187
@@ -111,6 +117,8 @@ def kernels(self, *filters):
111117
API Documentation: https://www.linode.com/docs/api/linode-instances/#kernels-list
112118
113119
:param filters: Any number of filters to apply to this query.
120+
See :doc:`Filtering Collections</linode_api4/objects/filtering>`
121+
for more details on filtering.
114122
115123
:returns: A list of available kernels that match the query.
116124
:rtype: PaginatedList of Kernel

‎linode_api4/groups/lke.py‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,9 @@ def versions(self, *filters):
2222
2323
API Documentation: https://www.linode.com/docs/api/linode-kubernetes-engine-lke/#kubernetes-versions-list
2424
25-
:param filters: Any number of filters to apply to the query.
25+
:param filters: Any number of filters to apply to this query.
26+
See :doc:`Filtering Collections</linode_api4/objects/filtering>`
27+
for more details on filtering.
2628
2729
:returns: A Paginated List of kube versions that match the query.
2830
:rtype: PaginatedList of KubeVersion
@@ -36,7 +38,9 @@ def clusters(self, *filters):
3638
3739
https://www.linode.com/docs/api/linode-kubernetes-engine-lke/#kubernetes-clusters-list
3840
39-
:param filters: Any number of filters to apply to the query.
41+
:param filters: Any number of filters to apply to this query.
42+
See :doc:`Filtering Collections</linode_api4/objects/filtering>`
43+
for more details on filtering.
4044
4145
:returns: A Paginated List of LKE clusters that match the query.
4246
:rtype: PaginatedList of LKECluster

‎linode_api4/groups/longview.py‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,8 @@ def clients(self, *filters):
2020
API Documentation: https://www.linode.com/docs/api/longview/#longview-clients-list
2121
2222
:param filters: Any number of filters to apply to this query.
23+
See :doc:`Filtering Collections</linode_api4/objects/filtering>`
24+
for more details on filtering.
2325
2426
:returns: A list of Longview Clients matching the given filters.
2527
:rtype: PaginatedList of LongviewClient
@@ -59,6 +61,8 @@ def subscriptions(self, *filters):
5961
API Documentation: https://www.linode.com/docs/api/longview/#longview-subscriptions-list
6062
6163
:param filters: Any number of filters to apply to this query.
64+
See :doc:`Filtering Collections</linode_api4/objects/filtering>`
65+
for more details on filtering.
6266
6367
:returns: A list of Longview Subscriptions matching the given filters.
6468
:rtype: PaginatedList of LongviewSubscription

‎linode_api4/groups/networking.py‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,8 @@ def firewalls(self, *filters):
2424
API Documentation: https://www.linode.com/docs/api/networking/#firewalls-list
2525
2626
:param filters: Any number of filters to apply to this query.
27+
See :doc:`Filtering Collections</linode_api4/objects/filtering>`
28+
for more details on filtering.
2729
2830
:returns: A list of Firewalls the acting user can access.
2931
:rtype: PaginatedList of Firewall
@@ -98,6 +100,8 @@ def ips(self, *filters):
98100
API Documentation: https://www.linode.com/docs/api/networking/#ip-addresses-list
99101
100102
:param filters: Any number of filters to apply to this query.
103+
See :doc:`Filtering Collections</linode_api4/objects/filtering>`
104+
for more details on filtering.
101105
102106
:returns: A list of IP addresses on this account.
103107
:rtype: PaginatedList of IPAddress
@@ -111,6 +115,8 @@ def ipv6_ranges(self, *filters):
111115
API Documentation: https://www.linode.com/docs/api/networking/#ipv6-ranges-list
112116
113117
:param filters: Any number of filters to apply to this query.
118+
See :doc:`Filtering Collections</linode_api4/objects/filtering>`
119+
for more details on filtering.
114120
115121
:returns: A list of IPv6 ranges on this account.
116122
:rtype: PaginatedList of IPv6Range
@@ -124,6 +130,8 @@ def ipv6_pools(self, *filters):
124130
API Documentation: https://www.linode.com/docs/api/networking/#ipv6-pools-list
125131
126132
:param filters: Any number of filters to apply to this query.
133+
See :doc:`Filtering Collections</linode_api4/objects/filtering>`
134+
for more details on filtering.
127135
128136
:returns: A list of IPv6 pools on this account.
129137
:rtype: PaginatedList of IPv6Pool
@@ -140,6 +148,8 @@ def vlans(self, *filters):
140148
API Documentation: https://www.linode.com/docs/api/networking/#vlans-list
141149
142150
:param filters: Any number of filters to apply to this query.
151+
See :doc:`Filtering Collections</linode_api4/objects/filtering>`
152+
for more details on filtering.
143153
144154
:returns: A List of VLANs on your account.
145155
:rtype: PaginatedList of VLAN

‎linode_api4/groups/nodebalancer.py‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,8 @@ def __call__(self, *filters):
1616
API Documentation: https://www.linode.com/docs/api/nodebalancers/#nodebalancers-list
1717
1818
:param filters: Any number of filters to apply to this query.
19+
See :doc:`Filtering Collections</linode_api4/objects/filtering>`
20+
for more details on filtering.
1921
2022
:returns: A list of NodeBalancers the acting user can access.
2123
:rtype: PaginatedList of NodeBalancers

0 commit comments

Comments
 (0)