apppy-aws 0.3.0__tar.gz

apppy_aws-0.3.0/.gitignore

@@ -0,0 +1,28 @@
+__generated__/
+dist/
+*.egg-info
+.env
+.env.*
+*.env
+!.env.ci
+.file_store/
+*.pid
+.python-version
+*.secrets
+.secrets
+*.tar.gz
+*.test_output/
+.test_output/
+uv.lock
+*.whl
+
+# System files
+__pycache__
+.DS_Store
+
+# Editor files
+*.sublime-project
+*.sublime-workspace
+.vscode/*
+!.vscode/settings.json
+

apppy_aws-0.3.0/PKG-INFO

@@ -0,0 +1,17 @@
+Metadata-Version: 2.4
+Name: apppy-aws
+Version: 0.3.0
+Summary: AWS integrations for server development
+Project-URL: Homepage, https://github.com/spals/apppy
+Author: Tim Kral
+License: MIT
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.11
+Requires-Dist: anyio==4.11.0
+Requires-Dist: apppy-env>=0.3.0
+Requires-Dist: apppy-fs>=0.3.0
+Requires-Dist: apppy-generic>=0.3.0
+Requires-Dist: apppy-logger>=0.3.0
+Requires-Dist: boto3-stubs[s3]==1.40.49
+Requires-Dist: boto3==1.40.49

apppy_aws-0.3.0/aws.mk

@@ -0,0 +1,23 @@
+ifndef APPPY_AWS_MK_INCLUDED
+APPPY_AWS_MK_INCLUDED := 1
+AWS_PKG_DIR := $(patsubst %/,%,$(dir $(abspath $(lastword $(MAKEFILE_LIST)))))
+
+.PHONY: aws aws-dev aws/build aws/clean aws/install aws/install-dev
+
+aws: aws/clean aws/install
+
+aws-dev: aws/clean aws/install-dev
+
+aws/build:
+	cd $(AWS_PKG_DIR) && uvx --from build pyproject-build
+
+aws/clean:
+	cd $(AWS_PKG_DIR) && rm -rf dist/ *.egg-info .venv
+
+aws/install: aws/build
+	cd $(AWS_PKG_DIR) && uv pip install dist/*.whl
+
+aws/install-dev:
+	cd $(AWS_PKG_DIR) && uv pip install -e .
+
+endif # APPPY_AWS_MK_INCLUDED

apppy_aws-0.3.0/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[dependency-groups]
+dev = []
+
+[project]
+name = "apppy-aws"
+description = "AWS integrations for server development"
+dynamic = ["version"]
+readme = "README.md"
+requires-python = ">=3.11"
+license = {text = "MIT"}
+authors = [{ name = "Tim Kral" }]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "License :: OSI Approved :: MIT License",
+]
+dependencies = [
+    "anyio==4.11.0",
+    "apppy-env>=0.3.0",
+    "apppy-fs>=0.3.0",
+    "apppy-generic>=0.3.0",
+    "apppy-logger>=0.3.0",
+    "boto3==1.40.49",
+    "boto3-stubs[s3]==1.40.49",
+]
+
+[project.urls]
+Homepage = "https://github.com/spals/apppy"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/apppy"]
+
+[tool.hatch.version]
+path = "../../VERSION"
+pattern = "^(?P<version>\\d+\\.\\d+\\.\\d+)$"
+source = "regex"
+
+[tool.uv.sources]
+apppy-env     = { workspace = true }
+apppy-fs      = { workspace = true }
+apppy-generic = { workspace = true }
+apppy-logger  = { workspace = true }

apppy_aws-0.3.0/src/apppy/aws/fs.py

@@ -0,0 +1,284 @@
+import uuid
+from pathlib import Path
+from typing import Any
+
+import boto3
+from anyio.to_thread import run_sync
+from botocore.exceptions import ClientError as BotoClientError
+from fastapi_lifespan_manager import LifespanManager
+from fsspec import AbstractFileSystem, register_implementation
+from mypy_boto3_s3 import S3Client
+from pydantic import Field
+from s3fs import S3FileSystem as NativeS3FileSystem
+
+from apppy.env import Env, EnvSettings
+from apppy.fs import (
+    FileSystem,
+    FileSystemBucket,
+    FileSystemPermission,
+    FileUrl,
+    GenericFileUrl,
+    ProxyFileSystem,
+)
+from apppy.fs.errors import (
+    FileSystemInvalidProtocolError,
+    MalformedFileUrlError,
+)
+from apppy.generic.encrypt import BytesEncrypter
+from apppy.logger import WithLogger
+
+
+class S3FileUrl(GenericFileUrl):
+    def __init__(
+        self,
+        _filesystem_protocol: str,
+        _filesystem_bucket: FileSystemBucket,
+        _filesystem_external_id: str | None,
+        _partition: str,
+        _directory: str | None,
+        _file_name: str | None,
+    ) -> None:
+        super().__init__(
+            _filesystem_protocol=_filesystem_protocol,
+            _filesystem_bucket=_filesystem_bucket,
+            _filesystem_external_id=_filesystem_external_id,
+            _partition=_partition,
+            _directory=_directory,
+            _file_name=_file_name,
+        )
+        str_instance = self.as_str_internal()
+
+        # Validation
+        if _filesystem_protocol != "enc://s3" and _filesystem_protocol != "s3":
+            raise FileSystemInvalidProtocolError(protocol=_filesystem_protocol)
+        # If we have an id, we must also have a file name
+        if _filesystem_external_id is not None and _file_name is None:
+            raise MalformedFileUrlError(
+                url=str_instance, code="s3_file_url_external_id_without_file_name"
+            )
+
+        self._key_prefix = str_instance[
+            len(f"{self.filesystem_protocol}://{_filesystem_bucket.value}") + 1 :
+        ]
+        self._key_prefix_parent = str(Path(self.key_prefix).parent)
+
+    @property
+    def key_prefix(self) -> str:
+        return self._key_prefix
+
+    @property
+    def key_prefix_parent(self) -> str:
+        return self._key_prefix_parent
+
+    @staticmethod
+    def split_path(path: str, protocol: str, bucket: FileSystemBucket) -> "S3FileUrl":
+        generic_file_url = GenericFileUrl.split_path(path=path, protocol=protocol, bucket=bucket)
+
+        return S3FileUrl(
+            _filesystem_protocol=generic_file_url.filesystem_protocol,
+            _filesystem_bucket=bucket,
+            _filesystem_external_id=generic_file_url.filesystem_external_id,
+            _partition=generic_file_url.partition,
+            _directory=generic_file_url.directory,
+            _file_name=generic_file_url.file_name,
+        )
+
+    @staticmethod
+    def split_url(url: str, bucket: FileSystemBucket) -> "S3FileUrl":
+        url = url.strip()
+        protocol = GenericFileUrl._parse_protocol(url, unencrypted=False)
+        path = url[len(f"{protocol}://") :]
+
+        return S3FileUrl.split_path(path=path, protocol=protocol, bucket=bucket)
+
+
+class S3FileSystemSettings(EnvSettings):
+    # S3_FS_BUCKET_EXTERNAL
+    bucket_external: str = Field()
+    # S3_FS_BUCKET_INTERNAL
+    bucket_internal: str = Field()
+    # S3_FS_REGION
+    region: str = Field()
+    # S3_FS_ENDPOINT
+    endpoint: str = Field()
+    # S3_FS_USE_SSL
+    use_ssl: bool = Field(default=True)
+    # S3_FS_VERSION_AWARE
+    version_aware: bool = Field(default=False)
+    # S3_FS_ACCESS_KEY_ID
+    access_key_id: str = Field()
+    # S3_FS_SECRET_ACCESS_KEY
+    secret_access_key: str = Field(exclude=True)
+    # S3_FS_ENCRYPT_PASSPHRASE
+    encrypt_passphrase: str | None = Field(default=None, exclude=True)
+    # S3_FS_ENCRYPT_SALT
+    encrypt_salt: str | None = Field(default=None, exclude=True)
+
+    def __init__(self, env: Env) -> None:
+        super().__init__(env=env, domain_prefix="S3_FS")
+
+
+class S3FileSystem(ProxyFileSystem, WithLogger):
+    def __init__(
+        self,
+        settings: S3FileSystemSettings,
+        lifespan: LifespanManager,
+        fs: FileSystem,
+    ) -> None:
+        self._settings: S3FileSystemSettings = settings
+
+        self._bytes_encrypter: BytesEncrypter | None = None
+        if (
+            settings.encrypt_passphrase is not None
+            and len(settings.encrypt_passphrase) > 0
+            and settings.encrypt_salt is not None
+            and len(settings.encrypt_salt) > 0
+        ):
+            self._bytes_encrypter = BytesEncrypter(
+                settings.encrypt_passphrase, settings.encrypt_salt
+            )
+
+        self._configure_nativefs(settings, fs)
+        lifespan.add(self.__configure_s3_storage)
+
+    def _configure_nativefs(
+        self,
+        settings: S3FileSystemSettings,
+        fs: FileSystem,
+    ) -> None:
+        # Use generic test buckets for all tests
+        self._bucket_external = FileSystemBucket(
+            bucket_type="external",
+            value=settings.bucket_external,
+        )
+        self._bucket_internal = FileSystemBucket(
+            bucket_type="internal",
+            value=settings.bucket_internal,
+        )
+
+        self._nativefs: NativeS3FileSystem = NativeS3FileSystem(
+            endpoint_url=settings.endpoint,
+            key=settings.access_key_id,
+            secret=settings.secret_access_key,
+            version_aware=settings.version_aware,
+        )
+        fs.register_proxyfs(self, "s3")
+        fs.register_nativefs(self._nativefs, "s3")
+
+        if self.is_encrypted:
+            # In the encrypted case, we'll need to also register the file
+            # system with fsspec itself so that the encrypted filesystem
+            # can instantiate it independently
+            register_implementation("sb", NativeS3FileSystem, clobber=True)
+
+    async def __configure_s3_storage(self):
+        self._logger.info("Creating S3 boto3 client for S3 filesystem bucket management")
+        s3: S3Client = boto3.client(
+            "s3",
+            region_name=self._settings.region,
+            endpoint_url=self._settings.endpoint,
+            aws_access_key_id=self._settings.access_key_id,
+            aws_secret_access_key=self._settings.secret_access_key,
+            use_ssl=self._settings.use_ssl,
+        )
+        try:
+            for bucket in (self._bucket_external, self._bucket_internal):
+                await run_sync(self.__ensure_s3_bucket, s3, bucket.value)
+        finally:
+            self._logger.info("Closing S3 boto3 client for S3 filesystem bucket management")
+            s3.close()
+
+        yield
+
+        self._logger.info("Closing S3 filesystem clients")
+
+    def __ensure_s3_bucket(self, s3: S3Client, bucket_name: str):
+        try:
+            s3.head_bucket(Bucket=bucket_name)
+            self._logger.info("Found bucket for S3 filesystem", extra={"bucket": bucket_name})
+        except BotoClientError as e:
+            error_code = e.response["Error"]["Code"]
+            if error_code == "404":
+                self._logger.info("Bucket missing for S3 filesystem", extra={"bucket": bucket_name})
+                if self._settings.region == "us-east-1":
+                    s3.create_bucket(Bucket=bucket_name)
+                else:
+                    s3.create_bucket(
+                        Bucket=bucket_name,
+                        CreateBucketConfiguration={"LocationConstraint": self._settings.region},  # type: ignore[typeddict-item]
+                    )
+                self._logger.info(
+                    "Created new bucket for S3 filesystem",
+                    extra={"bucket": bucket_name},
+                )
+            elif error_code == "403":
+                self._logger.warning(
+                    "Bucket access is forbidden while bootstrapping S3 filesystem",
+                    extra={"bucket": bucket_name},
+                )
+            else:
+                raise
+
+    def convert_file_url(self, file_url: FileUrl) -> FileUrl:
+        if isinstance(file_url, S3FileUrl) and self.is_encrypted == file_url.is_encrypted:
+            return file_url
+
+        if self.is_encrypted is True and file_url.is_encrypted is False:
+            # Add the encyption protocol if we need to
+            filesystem_protocol = f"enc://{file_url.filesystem_protocol}"
+        else:
+            filesystem_protocol = file_url.filesystem_protocol
+
+        # If we're not version aware, ensure that we have a unique id associated
+        # with the file_url. Unfortunately, it's not possible to get the actual
+        # unique identiter out of S3 storage so we'll just make one up here and
+        # pass it along
+        filesystem_external_id: str | None = (
+            str(uuid.uuid4())
+            if file_url.filesystem_external_id is None and self._settings.version_aware is False
+            else file_url.filesystem_external_id
+        )
+        return S3FileUrl(
+            _filesystem_protocol=filesystem_protocol,
+            _filesystem_bucket=(
+                self._bucket_external
+                if file_url.filesystem_bucket.is_external
+                else self._bucket_internal
+            ),
+            _filesystem_external_id=filesystem_external_id,
+            _partition=file_url.partition,
+            _directory=file_url.directory,
+            _file_name=file_url.file_name,
+        )
+
+    def file_url_kwargs(self, file_url: FileUrl) -> dict[str, Any]:
+        # No extra parameters needed
+        return {}
+
+    def parse_file_url(self, url: str) -> S3FileUrl:
+        if url.find(self._bucket_internal.value) > -1:
+            return S3FileUrl.split_url(url, self._bucket_internal)
+
+        return S3FileUrl.split_url(url, self._bucket_external)
+
+    def rm(self, url: str, recursive=False, maxdepth=None, **kwargs) -> None:
+        self.native.rm(url, recursive=recursive, maxdepth=maxdepth)
+
+    @property
+    def encryption(self) -> BytesEncrypter | None:
+        return self._bytes_encrypter
+
+    @property
+    def name(self) -> str:
+        return "AWS S3"
+
+    @property
+    def native(self) -> AbstractFileSystem:
+        return self._nativefs
+
+    @property
+    def permissions(self) -> list[FileSystemPermission]:
+        return [
+            FileSystemPermission.PRIVATE_INTERNAL,
+            FileSystemPermission.READWRITE,
+        ]

apppy_aws-0.3.0/src/apppy/aws/fs_unit_test.py

@@ -0,0 +1,273 @@
+import pytest
+
+from apppy.aws.fs import S3FileUrl
+from apppy.fs import FileSystemBucket, FileUrl
+
+_s3_filesystem_bucket_external = FileSystemBucket(bucket_type="external", value="fs_s3_test")
+
+_case_dir_only: S3FileUrl = S3FileUrl(
+    _filesystem_protocol="s3",
+    _filesystem_bucket=_s3_filesystem_bucket_external,
+    _filesystem_external_id=None,
+    _partition="partition",
+    _directory="dir",
+    _file_name=None,
+)
+_case_dir_with_subdir: S3FileUrl = S3FileUrl(
+    _filesystem_protocol="s3",
+    _filesystem_bucket=_s3_filesystem_bucket_external,
+    _filesystem_external_id=None,
+    _partition="partition",
+    _directory="dir/subdir",
+    _file_name=None,
+)
+# Valid url for version aware case
+_case_file_name_only: S3FileUrl = S3FileUrl(
+    _filesystem_protocol="s3",
+    _filesystem_bucket=_s3_filesystem_bucket_external,
+    _filesystem_external_id=None,
+    _partition="partition",
+    _directory=None,
+    _file_name="f.txt",
+)
+# Valid url for version aware case
+_case_file_name_with_dir: S3FileUrl = S3FileUrl(
+    _filesystem_protocol="s3",
+    _filesystem_bucket=_s3_filesystem_bucket_external,
+    _filesystem_external_id=None,
+    _partition="partition",
+    _directory="dir",
+    _file_name="f.txt",
+)
+# Malformed url for the S3 case
+# _case_unique_id_only: S3FileUrl = S3FileUrl(
+#     _filesystem_protocol="s3",
+#     _filesystem_bucket=_s3_filesystem_bucket_external,
+#     _filesystem_external_id="123-abc",
+#     _partition="partition",
+#     _directory=None,
+#     _file_name=None,
+# )
+# Malformed url for the S3 case
+# _case_unique_id_with_dir: S3FileUrl = S3FileUrl(
+#     _filesystem_protocol="s3",
+#     _filesystem_bucket=_s3_filesystem_bucket_external,
+#     _filesystem_external_id="123-abc",
+#     _partition="partition",
+#     _directory="dir",
+#     _file_name=None,
+# )
+_case_unique_id_with_dir_and_file_name: S3FileUrl = S3FileUrl(
+    _filesystem_protocol="s3",
+    _filesystem_bucket=_s3_filesystem_bucket_external,
+    _filesystem_external_id="123-abc",
+    _partition="partition",
+    _directory="dir",
+    _file_name="f.txt",
+)
+_case_unique_id_with_file_name: S3FileUrl = S3FileUrl(
+    _filesystem_protocol="s3",
+    _filesystem_bucket=_s3_filesystem_bucket_external,
+    _filesystem_external_id="123-abc",
+    _partition="partition",
+    _directory=None,
+    _file_name="f.txt",
+)
+_case_unique_id_with_dir_and_file_name_encrypted: S3FileUrl = S3FileUrl(
+    _filesystem_protocol="enc://s3",
+    _filesystem_bucket=_s3_filesystem_bucket_external,
+    _filesystem_external_id="123-abc",
+    _partition="partition",
+    _directory="dir",
+    _file_name="f.txt",
+)
+
+
+@pytest.mark.parametrize(
+    "file_url, expected_str",
+    [
+        (_case_dir_only, "s3://external/partition/dir"),
+        (_case_dir_with_subdir, "s3://external/partition/dir/subdir"),
+        (_case_file_name_only, "s3://external/partition/f.txt"),
+        (_case_file_name_with_dir, "s3://external/partition/dir/f.txt"),
+        (_case_unique_id_with_dir_and_file_name, "s3://external/partition/dir/@123-abc$f.txt"),
+        (_case_unique_id_with_file_name, "s3://external/partition/@123-abc$f.txt"),
+        (
+            _case_unique_id_with_dir_and_file_name_encrypted,
+            "enc://s3://external/partition/dir/@123-abc$f.txt",
+        ),
+    ],
+)
+def test_s3_file_url_str(file_url: FileUrl, expected_str: str):
+    assert str(file_url) == expected_str
+
+
+@pytest.mark.parametrize(
+    "file_url, expected_str",
+    [
+        (_case_dir_only, "s3://fs_s3_test/partition/dir"),
+        (_case_dir_with_subdir, "s3://fs_s3_test/partition/dir/subdir"),
+        (_case_file_name_only, "s3://fs_s3_test/partition/f.txt"),
+        (_case_file_name_with_dir, "s3://fs_s3_test/partition/dir/f.txt"),
+        (_case_unique_id_with_dir_and_file_name, "s3://fs_s3_test/partition/dir/@123-abc$f.txt"),
+        (_case_unique_id_with_file_name, "s3://fs_s3_test/partition/@123-abc$f.txt"),
+        (
+            _case_unique_id_with_dir_and_file_name_encrypted,
+            "s3://fs_s3_test/partition/dir/@123-abc$f.txt",
+        ),
+    ],
+)
+def test_s3_file_url_str_internal(file_url: FileUrl, expected_str: str):
+    assert file_url.as_str_internal() == expected_str
+
+
+@pytest.mark.parametrize(
+    "path, expected_file_url",
+    [
+        ("external/partition/dir", _case_dir_only),
+        ("external/partition/dir/subdir", _case_dir_with_subdir),
+        ("external/partition/f.txt", _case_file_name_only),
+        ("external/partition/dir/f.txt", _case_file_name_with_dir),
+        ("external/partition/dir/@123-abc$f.txt", _case_unique_id_with_dir_and_file_name),
+        ("external/partition/@123-abc$f.txt", _case_unique_id_with_file_name),
+    ],
+)
+def test_s3_file_url_split_path(path: str, expected_file_url: FileUrl):
+    file_url = S3FileUrl.split_path(path, protocol="s3", bucket=_s3_filesystem_bucket_external)
+    assert file_url == expected_file_url
+
+
+@pytest.mark.parametrize(
+    "path, expected_file_url",
+    [
+        ("fs_s3_test/partition/dir", _case_dir_only),
+        ("fs_s3_test/partition/dir/subdir", _case_dir_with_subdir),
+        ("fs_s3_test/partition/f.txt", _case_file_name_only),
+        ("fs_s3_test/partition/dir/f.txt", _case_file_name_with_dir),
+        ("fs_s3_test/partition/dir/@123-abc$f.txt", _case_unique_id_with_dir_and_file_name),
+        ("fs_s3_test/partition/@123-abc$f.txt", _case_unique_id_with_file_name),
+    ],
+)
+def test_s3_file_url_split_path_unobfuscated(path: str, expected_file_url: FileUrl):
+    file_url = S3FileUrl.split_path(path, protocol="s3", bucket=_s3_filesystem_bucket_external)
+    assert file_url == expected_file_url
+
+
+@pytest.mark.parametrize(
+    "url, expected_file_url",
+    [
+        ("s3://external/partition/dir", _case_dir_only),
+        ("s3://external/partition/dir/subdir", _case_dir_with_subdir),
+        ("s3://external/partition/f.txt", _case_file_name_only),
+        ("s3://external/partition/dir/f.txt", _case_file_name_with_dir),
+        ("s3://external/partition/dir/@123-abc$f.txt", _case_unique_id_with_dir_and_file_name),
+        ("s3://external/partition/@123-abc$f.txt", _case_unique_id_with_file_name),
+        (
+            "enc://s3://external/partition/dir/@123-abc$f.txt",
+            _case_unique_id_with_dir_and_file_name_encrypted,
+        ),
+    ],
+)
+def test_s3_file_url_split_url(url: str, expected_file_url: FileUrl):
+    file_url = S3FileUrl.split_url(url, bucket=_s3_filesystem_bucket_external)
+    assert file_url == expected_file_url
+
+
+@pytest.mark.parametrize(
+    "file_url, expected_key_prefix",
+    [
+        (_case_dir_only, "partition/dir"),
+        (_case_dir_with_subdir, "partition/dir/subdir"),
+        (_case_file_name_only, "partition/f.txt"),
+        (_case_file_name_with_dir, "partition/dir/f.txt"),
+        (_case_unique_id_with_dir_and_file_name, "partition/dir/@123-abc$f.txt"),
+        (_case_unique_id_with_file_name, "partition/@123-abc$f.txt"),
+    ],
+)
+def test_s3_file_url_key_prefix(file_url: S3FileUrl, expected_key_prefix: str):
+    assert file_url.key_prefix == expected_key_prefix
+
+
+@pytest.mark.parametrize(
+    "file_url, expected_key_prefix_parent",
+    [
+        (_case_dir_only, "partition"),
+        (_case_dir_with_subdir, "partition/dir"),
+        (_case_file_name_only, "partition"),
+        (_case_file_name_with_dir, "partition/dir"),
+        (_case_unique_id_with_dir_and_file_name, "partition/dir"),
+        (_case_unique_id_with_file_name, "partition"),
+    ],
+)
+def test_s3_file_url_key_prefix_parent(file_url: S3FileUrl, expected_key_prefix_parent: str):
+    assert file_url.key_prefix_parent == expected_key_prefix_parent
+
+
+@pytest.mark.parametrize(
+    "file_url",
+    [
+        (_case_dir_only),
+        (_case_dir_with_subdir),
+    ],
+)
+def test_s3_file_url_is_directory(file_url: FileUrl):
+    assert file_url.is_valid is True
+    assert file_url.is_directory is True
+    assert file_url.is_file is False
+
+
+@pytest.mark.parametrize(
+    "file_url",
+    [
+        (_case_file_name_only),
+        (_case_file_name_with_dir),
+        (_case_unique_id_with_dir_and_file_name),
+        (_case_unique_id_with_file_name),
+    ],
+)
+def test_s3_file_url_is_file(file_url: FileUrl):
+    assert file_url.is_valid is True
+    assert file_url.is_directory is False
+    assert file_url.is_file is True
+
+
+@pytest.mark.parametrize(
+    "file_url, join_dir, join_file_name, expected_joined_path",
+    [
+        (_case_dir_only, None, None, "s3://fs_s3_test/partition/dir"),
+        (_case_dir_only, "join_dir", None, "s3://fs_s3_test/partition/dir/join_dir"),
+        (_case_dir_only, None, "join_f.txt", "s3://fs_s3_test/partition/dir/join_f.txt"),
+        (
+            _case_dir_only,
+            "join_dir",
+            "join_f.txt",
+            "s3://fs_s3_test/partition/dir/join_dir/join_f.txt",
+        ),
+    ],
+)
+def test_s3_file_url_join(
+    file_url: S3FileUrl,
+    join_dir: str | None,
+    join_file_name: str | None,
+    expected_joined_path: str,
+):
+    joined_file_url = file_url.join(directory=join_dir, file_name=join_file_name)
+    assert joined_file_url.as_str_internal() == expected_joined_path
+
+
+@pytest.mark.parametrize(
+    "file_url, expected_parent_path",
+    [
+        (_case_dir_only, "s3://fs_s3_test/partition"),
+        (_case_dir_with_subdir, "s3://fs_s3_test/partition/dir"),
+        (_case_unique_id_with_dir_and_file_name, "s3://fs_s3_test/partition/dir"),
+        (_case_unique_id_with_file_name, "s3://fs_s3_test/partition"),
+        (
+            _case_unique_id_with_dir_and_file_name_encrypted,
+            "s3://fs_s3_test/partition/dir",
+        ),
+    ],
+)
+def test_s3_file_url_parent(file_url: S3FileUrl, expected_parent_path: str):
+    parent_file_url = file_url.parent()
+    assert parent_file_url.as_str_internal() == expected_parent_path