9class S3Key:
 10    """
 11    An Amazon Web Services S3 key.
 12    """
 13
 14    def __init__(self, key: Optional[str] = None) -> None:
 15        logger.debug('Creating new S3Key from "%s"', key)
 16        key = key or ""
 17
 18        if key.startswith("/"):
 19            raise ValueError(
 20                f'S3 keys cannot start with the delimiter "/" ("{key}")',
 21            )
 22
 23        if "//" in key:
 24            raise ValueError(
 25                f'S3 keys cannot contain consecutive "/" delimiters ("{key}")',
 26            )
 27
 28        if len(key) > MAX_LENGTH:
 29            raise ValueError(
 30                f"S3 keys cannot be longer than {MAX_LENGTH} characters "
 31                f'("{key}" has {len(key)} characters)',
 32            )
 33
 34        self._key = key or ""
 35
 36    def __add__(self, other: str) -> "S3Key":
 37        return self.append(other)
 38
 39    def __eq__(self, other: Any) -> bool:
 40        return self._key == str(other)
 41
 42    def __len__(self) -> int:
 43        return len(self._key)
 44
 45    def __repr__(self) -> str:
 46        return self._key
 47
 48    def __truediv__(self, other: str) -> "S3Key":
 49        return self.join(other)
 50
 51    def append(self, suffix: str) -> "S3Key":
 52        """
 53        Appends a string to the key.
 54
 55        ```python
 56        images = S3Key("images/staff-")
 57
 58        steve = images.append("steve.jpg")
 59        # "images/staff-steve.jpg"
 60
 61        # Or use "+":
 62        penny = images + "penny.jpg"
 63        # "images/staff-penny.jpg"
 64        ```
 65
 66        To add a suffix with a "/" delimiter, use `join()` instead.
 67        """
 68
 69        logger.debug('Appending base "%s" and suffix "%s"', self._key, suffix)
 70
 71        if self._key.endswith("/") and suffix.startswith("/"):
 72            base = self.normal_right(self._key, slash=True)
 73            logger.debug('Base normalised to "%s"', base)
 74            suffix = self.normal_left(suffix)
 75        else:
 76            base = self._key
 77
 78        return S3Key(base + suffix)
 79
 80    def join(self, suffix: str) -> "S3Key":
 81        """
 82        Joins a string to the key with a "/" delimiter.
 83
 84        ```python
 85        images = S3Key("images/staff")
 86
 87        steve = images.join("steve.jpg")
 88        # "images/staff/steve.jpg"
 89
 90        # Or use "/":
 91        penny = images / "penny.jpg"
 92        # "images/staff/penny.jpg"
 93        ```
 94
 95        To append a string without a "/" delimiter, use `append()` instead.
 96        """
 97
 98        logger.debug('Joining base "%s" and suffix "%s"', self._key, suffix)
 99
100        base = self.normal_right(self._key, slash=True) if self._key else self._key
101        logger.debug('Base normalised to "%s"', base)
102
103        suffix = self.normal_left(suffix)
104        logger.debug('Suffix normalised to "%s"', suffix)
105
106        return S3Key(base + suffix)
107
108    @property
109    def key(self) -> str:
110        """
111        Key.
112
113        For example, "private/clowns.jpg".
114        """
115
116        return self._key
117
118    @property
119    def leaf(self) -> str:
120        """
121        Key leaf.
122
123        In a file system metaphor, the leaf would be the file's name.
124
125        For example, the leaf of "private/clowns.jpg" is "clowns.jpg".
126        """
127
128        return self.relative_to(self.parent)
129
130    @staticmethod
131    def normal_left(key: str, slash: bool = False) -> str:
132        """
133        Normalises the left of the key.
134
135        If `slash` is true then the key is returned with exactly one leading
136        slash, otherwise the key is returned with no leading slashes.
137        """
138
139        while key.startswith("/"):
140            key = key[1:]
141
142        return "/" + key if slash else key
143
144    @staticmethod
145    def normal_right(key: str, slash: bool = False) -> str:
146        """
147        Normalises the right of the key.
148
149        If `slash` is true then the key is returned with exactly one trailing
150        slash, otherwise the key is returned with no trailing slashes.
151        """
152
153        while key.endswith("/"):
154            key = key[:-1]
155
156        return key + "/" if slash else key
157
158    @property
159    def parent(self) -> "S3Key":
160        """
161        Parent key.
162
163        For example, the parent of "private/clowns.jpg" is "private/".
164        """
165
166        logger.debug('Determining the parent of key "%s"', repr(self))
167
168        if self._key == "":
169            logger.debug("Empty key has no parent")
170            return self
171
172        if self._key.endswith("/"):
173            key = self._key[0:-1]
174        else:
175            key = self._key
176
177        if "/" not in key:
178            logger.debug("Root key parent is the root")
179            return S3Key()
180
181        index = key.rindex("/") + 1
182
183        logger.debug('Final "/" in key "%s" is at index %s', self._key, index)
184
185        parent_key = self._key[0:index]
186
187        logger.debug('Key "%s" parent is "%s"', self._key, parent_key)
188
189        return S3Key(parent_key)
190
191    def relative_to(self, parent: Union["S3Key", str]) -> str:
192        """
193        Gets the relative key path from this key to a `parent` key.
194
195        For example, the relative path to "private/clowns.jpg" from parent
196        "private" is "clowns.jpg".
197        """
198
199        logger.debug(
200            'Calculating the relative key from "%s" to "%s"',
201            self,
202            parent,
203        )
204
205        parent = str(parent)
206        normal = self.normal_right(parent, slash=True) if parent else parent
207
208        logger.debug('Normalised the parent key to "%s"', normal)
209
210        if not self._key.startswith(normal):
211            raise ValueError(f'"{parent}" is not a parent of "{self}"')
212
213        relative_key = self._key[len(normal) :]  # noqa: E203
214
215        logger.debug(
216            'The relative path from "%s" to "%s" is "%s"',
217            parent,
218            self,
219            relative_key,
220        )
221
222        return relative_key

  8class S3Uri:
  9    """
 10    An Amazon Web Services S3 URI.
 11
 12    To construct a URI from a bucket's name and optional key, use the
 13    `to_uri()` class method instead.
 14    """
 15
 16    def __init__(self, uri: str) -> None:
 17        m = match(r"[sS]3:\/\/([^/]*)(\/(.*))?", uri)
 18
 19        if not m:
 20            raise ValueError(f'"{uri}" is not an S3 URI')
 21
 22        self._bucket = str(m.group(1))
 23        self._key = S3Key(m.group(3))
 24
 25    def __add__(self, suffix: str) -> "S3Uri":
 26        return self.append(suffix)
 27
 28    def __eq__(self, other: Any) -> bool:
 29        return self.uri == str(other)
 30
 31    def __repr__(self) -> str:
 32        return self.uri
 33
 34    def __truediv__(self, suffix: str) -> "S3Uri":
 35        return self.join(suffix)
 36
 37    def append(self, other: str) -> "S3Uri":
 38        """
 39        Appends a string to the URI.
 40
 41        ```python
 42        images = S3Uri("s3://circus/staff-")
 43
 44        steve = images.append("steve.jpg")
 45        # "s3://circus/staff-steve.jpg"
 46
 47        # Or use "+":
 48        penny = images + "penny.jpg"
 49        # "s3://circus/staff-penny.jpg"
 50        ```
 51
 52        To add a suffix with a "/" delimiter, use `join()` instead.
 53        """
 54
 55        return S3Uri.to_uri(self._bucket, self._key.append(other))
 56
 57    @property
 58    def bucket(self) -> str:
 59        """
 60        Bucket.
 61        """
 62
 63        return self._bucket
 64
 65    def join(self, suffix: str) -> "S3Uri":
 66        """
 67        Joins a string to the URI with a "/" delimiter.
 68
 69        ```python
 70        images = S3Uri("s3://circus/staff")
 71
 72        steve = images.join("steve.jpg")
 73        # "s3://circus/staff/steve.jpg"
 74
 75        # Or use "/":
 76        penny = images / "penny.jpg"
 77        # "s3://circus/staff/penny.jpg"
 78        ```
 79
 80        To append a string without a "/" delimiter, use `append()` instead.
 81        """
 82
 83        return S3Uri.to_uri(self._bucket, self._key.join(suffix))
 84
 85    @property
 86    def key(self) -> S3Key:
 87        """
 88        Key.
 89        """
 90
 91        return self._key
 92
 93    @property
 94    def leaf(self) -> str:
 95        """
 96        URI leaf.
 97
 98        In a file system metaphor, the leaf would be the file's name.
 99
100        For example, the leaf of "s3://circus/private/clowns.jpg" is
101        "clowns.jpg".
102        """
103
104        return self.key.leaf
105
106    @property
107    def parent(self) -> "S3Uri":
108        """
109        Parent URI.
110
111        For example, the parent of "s3://circus/private/clowns.jpg" is
112        "s3://circus/private/".
113        """
114
115        return S3Uri.to_uri(self._bucket, self.key.parent)
116
117    def relative_to(self, parent: Union["S3Uri", str]) -> str:
118        """
119        Gets the relative key path from this URI to a `parent` URI.
120
121        For example, the relative path to "s3://circus/private/clowns.jpg" from
122        "s3://circus/" is "private/clowns.jpg".
123        """
124
125        parent = S3Uri(parent) if isinstance(parent, str) else parent
126
127        if parent._bucket != self._bucket:
128            raise ValueError(
129                f'There is no relative path from "{parent}" to "{self}" '
130                "because these URIs describe different buckets"
131            )
132
133        return self._key.relative_to(parent.key)
134
135    @staticmethod
136    def to_string(bucket: str, key: Optional[Union[S3Key, str]]) -> str:
137        """
138        Constructs a string S3 URI from a bucket and optional key.
139
140        To construct an `S3Uri` instance, use `to_uri()` instead.
141        """
142
143        return f"s3://{bucket}/{key or ''}"
144
145    @classmethod
146    def to_uri(
147        cls,
148        bucket: str,
149        key: Optional[Union[S3Key, str]] = None,
150    ) -> "S3Uri":
151        """
152        Constructs an `S3Uri` from a bucket and optional key.
153        """
154
155        return cls(cls.to_string(bucket, key=key))
156
157    @property
158    def uri(self) -> str:
159        """
160        URI.
161        """
162
163        return self.to_string(self._bucket, self._key)