doc: Improve filtering documentation (linode#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 linode#217

Author: lgarber-akamai

docs/guides/core_concepts.rst

@@ -49,12 +49,13 @@ certain group.  This library implements filtering with a SQLAlchemy-like
 syntax, where a model's attributes may be used in comparisons to generate
 filters.  For example::
 
+   from linode_api4 import Instance
+
    prod_linodes = client.linode.instances(Instance.group == "production")
 
 Filters may be combined using boolean operators similar to SQLAlchemy::
 
    # and_ and or_ can be imported from the linode package to combine filters
-   from linode_api4 import or_
    prod_or_staging = client.linode.instances(or_(Instance.group == "production",
                                                      Instance.group == "staging"))
 
@@ -66,7 +67,7 @@ Filters may be combined using boolean operators similar to SQLAlchemy::
 Filters are generally only applicable for the type of model you are querying,
 but can be combined to your heart's content.  For numeric fields, the standard
 numeric comparisons are accepted, and work as you'd expect.  See
-:doc:`Filtering Collections<../linode/objects/filtering>` for full details.
+:doc:`Filtering Collections</linode_api4/objects/filtering>` for full details.
 
 Models
 ------

linode_api4/groups/account.py

@@ -49,6 +49,8 @@ def events(self, *filters):
         API Documentation: https://www.linode.com/docs/api/account/#events-list
 
         :param filters: Any number of filters to apply to this query.
+                        See :doc:`Filtering Collections</linode_api4/objects/filtering>`
+                        for more details on filtering.
 
         :returns: A list of events on the current account matching the given filters.
         :rtype: PaginatedList of Event
@@ -124,6 +126,8 @@ def oauth_clients(self, *filters):
         API Documentation: https://www.linode.com/docs/api/account/#oauth-clients-list
 
         :param filters: Any number of filters to apply to this query.
+                        See :doc:`Filtering Collections</linode_api4/objects/filtering>`
+                        for more details on filtering.
 
         :returns: A list of OAuth Clients associated with this account.
         :rtype: PaginatedList of OAuthClient
@@ -167,6 +171,8 @@ def users(self, *filters):
         API Documentation: https://www.linode.com/docs/api/account/#users-list
 
         :param filters: Any number of filters to apply to this query.
+                        See :doc:`Filtering Collections</linode_api4/objects/filtering>`
+                        for more details on filtering.
 
         :returns: A list of users on this account.
         :rtype: PaginatedList of User

linode_api4/groups/database.py

@@ -33,7 +33,9 @@ def types(self, *filters):
 
         API Documentation: https://www.linode.com/docs/api/databases/#managed-database-types-list
 
-        :param filters: Any number of filters to apply to the query.
+        :param filters: Any number of filters to apply to this query.
+                        See :doc:`Filtering Collections</linode_api4/objects/filtering>`
+                        for more details on filtering.
 
         :returns: A list of types that match the query.
         :rtype: PaginatedList of DatabaseType
@@ -51,7 +53,9 @@ def engines(self, *filters):
 
         API Documentation: https://www.linode.com/docs/api/databases/#managed-database-engines-list
 
-        :param filters: Any number of filters to apply to the query.
+        :param filters: Any number of filters to apply to this query.
+                        See :doc:`Filtering Collections</linode_api4/objects/filtering>`
+                        for more details on filtering.
 
         :returns: A list of types that match the query.
         :rtype: PaginatedList of DatabaseEngine
@@ -65,6 +69,8 @@ def instances(self, *filters):
         API Documentation: https://www.linode.com/docs/api/databases/#managed-databases-list-all
 
         :param filters: Any number of filters to apply to this query.
+                        See :doc:`Filtering Collections</linode_api4/objects/filtering>`
+                        for more details on filtering.
 
         :returns: A list of databases that matched the query.
         :rtype: PaginatedList of Database
@@ -78,6 +84,8 @@ def mysql_instances(self, *filters):
         API Documentation: https://www.linode.com/docs/api/databases/#managed-mysql-databases-list
 
         :param filters: Any number of filters to apply to this query.
+                        See :doc:`Filtering Collections</linode_api4/objects/filtering>`
+                        for more details on filtering.
 
         :returns: A list of MySQL databases that matched the query.
         :rtype: PaginatedList of MySQLDatabase
@@ -141,6 +149,8 @@ def postgresql_instances(self, *filters):
         API Documentation: https://www.linode.com/docs/api/databases/#managed-postgresql-databases-list
 
         :param filters: Any number of filters to apply to this query.
+                        See :doc:`Filtering Collections</linode_api4/objects/filtering>`
+                        for more details on filtering.
 
         :returns: A list of PostgreSQL databases that matched the query.
         :rtype: PaginatedList of PostgreSQLDatabase

linode_api4/groups/domain.py

@@ -16,6 +16,8 @@ def __call__(self, *filters):
         API Documentation: https://www.linode.com/docs/api/domains/#domains-list
 
         :param filters: Any number of filters to apply to this query.
+                        See :doc:`Filtering Collections</linode_api4/objects/filtering>`
+                        for more details on filtering.
 
         :returns: A list of Domains the acting user can access.
         :rtype: PaginatedList of Domain

linode_api4/groups/image.py

@@ -20,7 +20,9 @@ def __call__(self, *filters):
 
         API Documentation: https://www.linode.com/docs/api/images/#images-list
 
-        :param filters: Any number of filters to apply to the query.
+        :param filters: Any number of filters to apply to this query.
+                        See :doc:`Filtering Collections</linode_api4/objects/filtering>`
+                        for more details on filtering.
 
         :returns: A list of available Images.
         :rtype: PaginatedList of Image

linode_api4/groups/linode.py

@@ -41,7 +41,9 @@ def types(self, *filters):
 
         API documentation: https://www.linode.com/docs/api/linode-types/#types-list
 
-        :param filters: Any number of filters to apply to the query.
+        :param filters: Any number of filters to apply to this query.
+                        See :doc:`Filtering Collections</linode_api4/objects/filtering>`
+                        for more details on filtering.
 
         :returns: A list of types that match the query.
         :rtype: PaginatedList of Type
@@ -58,6 +60,8 @@ def instances(self, *filters):
         API Documentation: https://www.linode.com/docs/api/linode-instances/#linodes-list
 
         :param filters: Any number of filters to apply to this query.
+                        See :doc:`Filtering Collections</linode_api4/objects/filtering>`
+                        for more details on filtering.
 
         :returns: A list of Instances that matched the query.
         :rtype: PaginatedList of Instance
@@ -76,6 +80,8 @@ def stackscripts(self, *filters, **kwargs):
         API Documentation: https://www.linode.com/docs/api/stackscripts/#stackscripts-list
 
         :param filters: Any number of filters to apply to this query.
+                        See :doc:`Filtering Collections</linode_api4/objects/filtering>`
+                        for more details on filtering.
         :param mine_only: If True, returns only private StackScripts
         :type mine_only: bool
 
@@ -111,6 +117,8 @@ def kernels(self, *filters):
         API Documentation: https://www.linode.com/docs/api/linode-instances/#kernels-list
 
         :param filters: Any number of filters to apply to this query.
+                        See :doc:`Filtering Collections</linode_api4/objects/filtering>`
+                        for more details on filtering.
 
         :returns: A list of available kernels that match the query.
         :rtype: PaginatedList of Kernel

linode_api4/groups/lke.py

@@ -22,7 +22,9 @@ def versions(self, *filters):
 
         API Documentation: https://www.linode.com/docs/api/linode-kubernetes-engine-lke/#kubernetes-versions-list
 
-        :param filters: Any number of filters to apply to the query.
+        :param filters: Any number of filters to apply to this query.
+                        See :doc:`Filtering Collections</linode_api4/objects/filtering>`
+                        for more details on filtering.
 
         :returns: A Paginated List of kube versions that match the query.
         :rtype: PaginatedList of KubeVersion
@@ -36,7 +38,9 @@ def clusters(self, *filters):
 
         https://www.linode.com/docs/api/linode-kubernetes-engine-lke/#kubernetes-clusters-list
 
-        :param filters: Any number of filters to apply to the query.
+        :param filters: Any number of filters to apply to this query.
+                        See :doc:`Filtering Collections</linode_api4/objects/filtering>`
+                        for more details on filtering.
 
         :returns: A Paginated List of LKE clusters that match the query.
         :rtype: PaginatedList of LKECluster

linode_api4/groups/longview.py

@@ -20,6 +20,8 @@ def clients(self, *filters):
         API Documentation: https://www.linode.com/docs/api/longview/#longview-clients-list
 
         :param filters: Any number of filters to apply to this query.
+                        See :doc:`Filtering Collections</linode_api4/objects/filtering>`
+                        for more details on filtering.
 
         :returns: A list of Longview Clients matching the given filters.
         :rtype: PaginatedList of LongviewClient
@@ -59,6 +61,8 @@ def subscriptions(self, *filters):
         API Documentation: https://www.linode.com/docs/api/longview/#longview-subscriptions-list
 
         :param filters: Any number of filters to apply to this query.
+                        See :doc:`Filtering Collections</linode_api4/objects/filtering>`
+                        for more details on filtering.
 
         :returns: A list of Longview Subscriptions matching the given filters.
         :rtype: PaginatedList of LongviewSubscription

linode_api4/groups/networking.py

@@ -24,6 +24,8 @@ def firewalls(self, *filters):
         API Documentation: https://www.linode.com/docs/api/networking/#firewalls-list
 
         :param filters: Any number of filters to apply to this query.
+                        See :doc:`Filtering Collections</linode_api4/objects/filtering>`
+                        for more details on filtering.
 
         :returns: A list of Firewalls the acting user can access.
         :rtype: PaginatedList of Firewall
@@ -98,6 +100,8 @@ def ips(self, *filters):
         API Documentation: https://www.linode.com/docs/api/networking/#ip-addresses-list
 
         :param filters: Any number of filters to apply to this query.
+                        See :doc:`Filtering Collections</linode_api4/objects/filtering>`
+                        for more details on filtering.
 
         :returns: A list of IP addresses on this account.
         :rtype: PaginatedList of IPAddress
@@ -111,6 +115,8 @@ def ipv6_ranges(self, *filters):
         API Documentation: https://www.linode.com/docs/api/networking/#ipv6-ranges-list
 
         :param filters: Any number of filters to apply to this query.
+                        See :doc:`Filtering Collections</linode_api4/objects/filtering>`
+                        for more details on filtering.
 
         :returns: A list of IPv6 ranges on this account.
         :rtype: PaginatedList of IPv6Range
@@ -124,6 +130,8 @@ def ipv6_pools(self, *filters):
         API Documentation: https://www.linode.com/docs/api/networking/#ipv6-pools-list
 
         :param filters: Any number of filters to apply to this query.
+                        See :doc:`Filtering Collections</linode_api4/objects/filtering>`
+                        for more details on filtering.
 
         :returns: A list of IPv6 pools on this account.
         :rtype: PaginatedList of IPv6Pool
@@ -140,6 +148,8 @@ def vlans(self, *filters):
         API Documentation: https://www.linode.com/docs/api/networking/#vlans-list
 
         :param filters: Any number of filters to apply to this query.
+                        See :doc:`Filtering Collections</linode_api4/objects/filtering>`
+                        for more details on filtering.
 
         :returns: A List of VLANs on your account.
         :rtype: PaginatedList of VLAN

linode_api4/groups/nodebalancer.py

@@ -16,6 +16,8 @@ def __call__(self, *filters):
         API Documentation: https://www.linode.com/docs/api/nodebalancers/#nodebalancers-list
 
         :param filters: Any number of filters to apply to this query.
+                        See :doc:`Filtering Collections</linode_api4/objects/filtering>`
+                        for more details on filtering.
 
         :returns: A list of NodeBalancers the acting user can access.
         :rtype: PaginatedList of NodeBalancers

linode_api4/groups/obj.py

@@ -19,6 +19,8 @@ def clusters(self, *filters):
         API Documentation: https://www.linode.com/docs/api/object-storage/#clusters-list
 
         :param filters: Any number of filters to apply to this query.
+                        See :doc:`Filtering Collections</linode_api4/objects/filtering>`
+                        for more details on filtering.
 
         :returns: A list of Object Storage Clusters that matched the query.
         :rtype: PaginatedList of ObjectStorageCluster
@@ -33,6 +35,8 @@ def keys(self, *filters):
         API Documentation: https://www.linode.com/docs/api/object-storage/#object-storage-keys-list
 
         :param filters: Any number of filters to apply to this query.
+                        See :doc:`Filtering Collections</linode_api4/objects/filtering>`
+                        for more details on filtering.
 
         :returns: A list of Object Storage Keys that matched the query.
         :rtype: PaginatedList of ObjectStorageKeys

linode_api4/groups/object_storage.py

@@ -27,6 +27,8 @@ def clusters(self, *filters):
         API Documentation: https://www.linode.com/docs/api/object-storage/#clusters-list
 
         :param filters: Any number of filters to apply to this query.
+                        See :doc:`Filtering Collections</linode_api4/objects/filtering>`
+                        for more details on filtering.
 
         :returns: A list of Object Storage Clusters that matched the query.
         :rtype: PaginatedList of ObjectStorageCluster
@@ -41,6 +43,8 @@ def keys(self, *filters):
         API Documentation: https://www.linode.com/docs/api/object-storage/#object-storage-keys-list
 
         :param filters: Any number of filters to apply to this query.
+                        See :doc:`Filtering Collections</linode_api4/objects/filtering>`
+                        for more details on filtering.
 
         :returns: A list of Object Storage Keys that matched the query.
         :rtype: PaginatedList of ObjectStorageKeys
@@ -174,6 +178,10 @@ def buckets(self, *filters):
 
         API Documentation: https://www.linode.com/docs/api/object-storage/#object-storage-buckets-list
 
+        :param filters: Any number of filters to apply to this query.
+                        See :doc:`Filtering Collections</linode_api4/objects/filtering>`
+                        for more details on filtering.
+
         :returns: A list of Object Storage Buckets that matched the query.
         :rtype: PaginatedList of ObjectStorageBucket
         """

linode_api4/groups/profile.py

@@ -227,6 +227,8 @@ def tokens(self, *filters):
         API Documentation: https://www.linode.com/docs/api/profile/#personal-access-tokens-list
 
         :param filters: Any number of filters to apply to this query.
+                        See :doc:`Filtering Collections</linode_api4/objects/filtering>`
+                        for more details on filtering.
 
         :returns: A list of tokens that matches the query.
         :rtype: PaginatedList of PersonalAccessToken
@@ -276,6 +278,8 @@ def apps(self, *filters):
         API Documentation: https://www.linode.com/docs/api/profile/#authorized-apps-list
 
         :param filters: Any number of filters to apply to this query.
+                        See :doc:`Filtering Collections</linode_api4/objects/filtering>`
+                        for more details on filtering.
 
         :returns: A list of Authorized Applications for this user
         :rtype: PaginatedList of AuthorizedApp
@@ -289,6 +293,8 @@ def ssh_keys(self, *filters):
         API Documentation: https://www.linode.com/docs/api/profile/#ssh-keys-list
 
         :param filters: Any number of filters to apply to this query.
+                        See :doc:`Filtering Collections</linode_api4/objects/filtering>`
+                        for more details on filtering.
 
         :returns: A list of SSH Keys for this profile.
         :rtype: PaginatedList of SSHKey

linode_api4/groups/region.py

@@ -14,7 +14,9 @@ def __call__(self, *filters):
 
         API Documentation: https://www.linode.com/docs/api/regions/#regions-list
 
-        :param filters: Any number of filters to apply to the query.
+        :param filters: Any number of filters to apply to this query.
+                        See :doc:`Filtering Collections</linode_api4/objects/filtering>`
+                        for more details on filtering.
 
         :returns: A list of available Regions.
         :rtype: PaginatedList of Region

linode_api4/groups/support.py

@@ -26,6 +26,8 @@ def tickets(self, *filters):
         API Documentation: https://www.linode.com/docs/api/support/#support-tickets-list
 
         :param filters: Any number of filters to apply to this query.
+                        See :doc:`Filtering Collections</linode_api4/objects/filtering>`
+                        for more details on filtering.
 
         :returns: A list of support tickets on this account.
         :rtype: PaginatedList of SupportTicket

linode_api4/groups/tag.py

@@ -17,6 +17,8 @@ def __call__(self, *filters):
         API Documentation: https://www.linode.com/docs/api/domains/#domain-create
 
         :param filters: Any number of filters to apply to this query.
+                        See :doc:`Filtering Collections</linode_api4/objects/filtering>`
+                        for more details on filtering.
 
         :returns: A list of Tags on the account.
         :rtype: PaginatedList of Tag

linode_api4/groups/volume.py

@@ -16,6 +16,8 @@ def __call__(self, *filters):
         API Documentation: https://www.linode.com/docs/api/volumes/#volumes-list
 
         :param filters: Any number of filters to apply to this query.
+                        See :doc:`Filtering Collections</linode_api4/objects/filtering>`
+                        for more details on filtering.
 
         :returns: A list of Volumes the acting user can access.
         :rtype: PaginatedList of Volume

linode_api4/objects/filtering.py

@@ -6,6 +6,12 @@
 class of one of its groups, any number of filters may be passed in as boolean
 comparisons between attributes of the model returned by the collection.
 
+When filtering on API responses for list endpoints, you will first need
+to import the corresponding object class.
+For example, to filter on instances you must first Import :any:`Instance`::
+
+    from linode_api4 import Instance
+
 For example, calling :any:`instances` returns a list of :any:`Instance`
 objects, so we can use properties of :any:`Instance` to filter the results::
 

linode_api4/objects/object_storage.py

@@ -481,8 +481,9 @@ def buckets_in_cluster(self, *filters):
 
         API Documentation: https://www.linode.com/docs/api/object-storage/#object-storage-buckets-in-cluster-list
 
-        :param cluster_id: The ID of the cluster this bucket exists in.
-        :type cluster_id: str
+        :param filters: Any number of filters to apply to this query.
+                        See :doc:`Filtering Collections</linode_api4/objects/filtering>`
+                        for more details on filtering.
 
         :returns: A list of Object Storage Buckets that in the requested cluster.
         :rtype: PaginatedList of ObjectStorageBucket