Resource gate builder¶
module: rspub.pluggable.gate
Pluggable resource gate and builder
Build your own¶
The selection mechanism for resources is implemented as a gate() that uses
predicates for including and excluding resources based on their filename.
The ResourceGateBuilder hook allows you to shape this resource gate and adapt it
completely to your needs. You can build your own ResourceGateBuilder by creating a class that subclasses
rspub.pluggable.gate.ResourceGateBuilder or - to avoid dependencies in your code - that implements the two
methods build_includes() and build_excludes().
In any case your gate builder should be named ResourceGateBuilder, because by this name your plugin will be
recognized by rspub-core.
Register a ResourceGateBuilder¶
Your ResourceGateBuilder should be placed in a directory that is registered
as plugin_dir() at ResourceSync.
(There may be multiple ResourceGateBuilders in your plugin directory but this could unnecessarily complicate
the building process.)
Build predicates¶
Predicates you supply in the lists of including and excluding predicates should be one-argument predicates
that take the filename of a resource as input. The logic in your predicates could take advantage of the
logical functions offered by rspub.util.gates and file selection filters offered
in rspub.util.resourcefilter.
Example: Construct a predicate for directory names that end with ‘abc’:
import rspub.util.resourcefilter as rf
dir_ends_with_abc = rf.directory_pattern_predicate("abc$")
assert dir_ends_with_abc("/foo/bar/folder_abc/my_resource.txt")
assert not dir_ends_with_abc("/foo/bar/folder_def/my_resource.txt")
Example: Construct a predicate for xml files:
xml_file = rf.filename_pattern_predicate(".xml$")
assert xml_file("my_resource.xml")
assert not xml_file("my_resource.txt")
Example: Construct a predicate for xml files in folders that end with ‘abc’:
import rspub.util.gates as lf
xml_file_in_abc = lf.and_(dir_ends_with_abc, xml_file)
assert xml_file_in_abc("/foo/bar/folder_abc/my_resource.xml")
assert not xml_file_in_abc("/foo/bar/folder_abc/my_resource.txt")
assert not xml_file_in_abc("/foo/bar/folder_def/my_resource.xml")
Example: Construct a predicate for files modified after 31 July 2016:
recent = rf.last_modified_after_predicate("2016-08-01")
Example: Test a gate that will allow xml files from folders that end with ‘abc’, but that excludes files modified after 31 July 2016:
includes = [xml_files_in_abc]
excludes = [recent]
resource_gate = lf.gate(includes, excludes)
If you are satisfied with your gate the includes and excludes can be contributed by your ResourceGateBuilder.
Implement the build methods¶
When implementing the build methods build_includes()
and build_excludes() it is good to know that the first builder in the chain
is the default ResourceGateBuilder as implemented below. It defines the includes very wide: allow anything
found in the resource_dir(). In order to effectively contribute your
including predicates, you should not append them to the given list but replace the list with your own list
of predicates. The excluding list as defined by the default class:ResourceGateBuilder contains niceties as
filter out hidden files, exclude files in your metadata_dir() etc.
If these default excluding predicates are not in your way you can append your excludes to this default list
in the method build_excludes().
-
class
rspub.pluggable.gate.ResourceGateBuilder(resource_dir=None, metadata_dir=None, plugin_dir=None)[source]¶ Bases:
rspub.util.gates.GateBuilderDefault ResourceGateBuilderThis default class builds a
gate()that allows any file that is encountered. It will exclude however any file that is not inresource_dir()or any of its subdirectories, hidden files and files from the directoriesmetadata_dir(),plugin_dir()and .well-known/resourcesync.