Side-by-side compare

Here's a Python function that expands a leading `~` (or `~user`) and returns an absolute `pathlib.Path`:

```python
from pathlib import Path

def expand_user_path(path: str | Path) -> Path:
    """
    Expand a user path that may start with ~ and return an absolute Path.

    Handles:
      - '~/documents'  -> /home/username/documents
      - '~other/file'  -> /home/other/file (if that user exists)
      - relative paths -> made absolute against the current working directory
      - absolute paths -> returned unchanged (after ~ expansion)

    Args:
        path: A string or Path object.

    Returns:
        An absolute pathlib.Path object.
    """
    # Convert to Path, expand ~ and ~user
    expanded = Path(path).expanduser()

    # If still relative, anchor it to the current working directory
    if not expanded.is_absolute():
        expanded = Path.cwd() / expanded

    return expanded
```

**Usage example:**

```python
>>> expand_user_path("~/projects/notes.txt")
PosixPath('/home/alice/projects/notes.txt')

>>> expand_user_path("docs/report.pdf")
PosixPath('/home/alice/current/working/dir/docs/report.pdf')
```

**Notes:**
- `Path.expanduser()` handles both `~` and `~username`.
- The function does **not** resolve symlinks or

Here's a Python function that converts a Unix timestamp (in seconds) to an aware UTC `datetime` object:

```python
from datetime import datetime, timezone

def unix_timestamp_to_utc(timestamp: float) -> datetime:
    """
    Convert a Unix timestamp (seconds since epoch) to an aware UTC datetime.

    Args:
        timestamp: Unix timestamp in seconds (int or float).

    Returns:
        An aware datetime object with UTC timezone.
    """
    return datetime.fromtimestamp(timestamp, tz=timezone.utc)
```

### Usage example:
```python
>>> unix_timestamp_to_utc(1700000000)
datetime.datetime(2023, 11, 14, 22, 13, 20, tzinfo=datetime.timezone.utc)
```

### Why this works:
- `datetime.fromtimestamp(timestamp, tz=timezone.utc)` creates a datetime in the specified timezone (UTC) directly.
- The returned object is **aware** because it includes a `tzinfo` set to `timezone.utc`.
- The function accepts both integers and floats; fractional seconds are preserved as microseconds.

If you prefer a more explicit alternative (though slightly less direct), you could use:

```python
def unix_timestamp_to_utc(timestamp: float) -> datetime:
    from datetime import datetime, timezone
    return datetime.utcfromtimestamp(timestamp).replace(tzinfo=timezone.utc)
```

But the first version is recommended because `utcfromtimestamp()` is considered deprecated in Python 3.12+ and returns a naive datetime that you then have to "attach" timezone info to. The `fromtimestamp(..., tz=...)` approach is cleaner and future-proof.

Below is a Python function that ensures a directory exists, creating it and any missing parent directories as needed, and returns the corresponding `pathlib.Path` object.

```python
from pathlib import Path

def ensure_dir(path):
    """
    Ensure a directory exists at the given path, creating it and all
    missing parent directories if necessary.

    Args:
        path (str or Path): The directory path to ensure.

    Returns:
        Path: The Path object of the ensured directory.

    Raises:
        FileExistsError: If the path exists but is not a directory.
        OSError: If the directory cannot be created (e.g., permission issues).
    """
    p = Path(path)
    p.mkdir(parents=True, exist_ok=True)
    return p
```

### How it works:
- `Path(path)` converts the input to a `pathlib.Path` object.
- `mkdir(parents=True, exist_ok=True)` creates the directory and all intermediate directories.  
  - `parents=True` ensures parent directories are created as needed.  
  - `exist_ok=True` prevents an error if the directory already exists.  
- The function returns the `Path` object for further use.

### Example usage:
```python
# Create a nested directory structure
dir_path = ensure_dir("data/raw/2024")
print(dir_path)  # Output: data/raw/2024
print(dir_path.exists())  # True
print(dir_path.is_dir())  # True
```

### Edge cases:
- If the path already exists as a file, `mkdir` will raise a `FileExistsError` (since `exist_ok=True` only suppresses errors when the path is a directory).
- If the path is empty or `.`, it will ensure the current directory exists (which it always does) and return a `Path('.')`.

This function is safe, concise, and leverages Python's standard library for robust filesystem operations.