- ltdconveyor.s3.upload_dir(bucket_name, path_prefix, source_dir, upload_dir_redirect_objects=True, surrogate_key=None, surrogate_control=None, cache_control=None, acl=None, aws_access_key_id=None, aws_secret_access_key=None, aws_profile=None)#
Upload a directory of files to S3.
This function places the contents of the Sphinx HTML build directory into the
/path_prefix/directory of an existing S3 bucket. Existing files on S3 are overwritten; files that no longer exist in the
source_dirare deleted from S3.
bucket_name (str) – Name of the S3 bucket where documentation is uploaded.
path_prefix (str) – The root directory in the bucket where documentation is stored.
source_dir (str) – Path of the Sphinx HTML build directory on the local file system. The contents of this directory are uploaded into the
/path_prefix/directory of the S3 bucket.
upload_dir_redirect_objects (bool, optional) – A feature flag to enable uploading objects to S3 for every directory. These objects contain
x-amz-meta-dir-redirect=trueHTTP headers that tell Fastly to issue a 301 redirect from the directory object to the index.html` in that directory.
surrogate_key (str, optional) – The surrogate key to insert in the header of all objects in the
x-amz-meta-surrogate-keyfield. This key is used to purge builds from the Fastly CDN when Editions change. If None then no header will be set.
cache_control (str, optional) – This sets the
Cache-Controlheader on the uploaded files. The
Cache-Controlheader specifically dictates how content is cached by the browser (if
surrogate_controlis also set).
surrogate_control (str, optional) – This sets the
x-amz-meta-surrogate-controlheader on the uploaded files. The
x-amz-meta-surrogate-controlheader is used in priority by Fastly to givern it’s caching. This caching policy is not passed to the browser.
acl (str, optional) – The pre-canned AWS access control list to apply to this upload. Can be
'public-read', which allow files to be downloaded over HTTP by the public. See https://docs.aws.amazon.com/AmazonS3/latest/dev/acl-overview.html#canned-acl for an overview of S3’s pre-canned ACL lists. Note that ACL settings are not validated locally. Default is None, meaning that no ACL is applied to an individual object. In this case, use ACLs applied to the bucket itself.
aws_access_key_id (str, optional) – The access key for your AWS account. Also set
aws_secret_access_key (str, optional) – The secret key for your AWS account.
aws_profile (str, optional) – Name of AWS profile in
~/.aws/credentials. Use this instead of
aws_secret_access_keyfor file-based credentials.
- Return type:
surrogate_controlcan be used together.
surrogate_controltakes priority in setting Fastly’s POP caching, while
cache_controlthen sets the browser’s caching. For example:
together will ensure that the browser always does an ETAG server query, but that Fastly will cache the content for one year (or until purged). This configuration is good for files that are frequently changed in place.
For immutable uploads simply using
cache_controlis more efficient since it allows the browser to also locally cache content.