Skip to content

refactor: Improve host handling and add comprehensive documentation#22

Merged
qjerome merged 1 commit intomainfrom
refactor/host-api-improvements
Mar 3, 2026
Merged

refactor: Improve host handling and add comprehensive documentation#22
qjerome merged 1 commit intomainfrom
refactor/host-api-improvements

Conversation

@qjerome
Copy link
Collaborator

@qjerome qjerome commented Mar 3, 2026

Summary
Comprehensive refactoring of host-related functionality in Python APIs, adding documentation, fixing architectural issues, and updating tests. This fixes issue #19.

Motivation
The Python API is missing a way to use the parsed Host from a Url without reparsing it again (see #19).

Changes

Rust Library:

  • Make Url.host field pub and document it

Python Bindings:

  • Added Display trait implementation for Host enum
  • Added Clone derive for Host enum to fix PyO3 compatibility
  • Added methods for Host struct Host::domain(), Host::subdomain, Host::suffix + documentation
  • Updated FaupCompat methods to use proper Host method calls instead of direct field access:
    • get_domain(): Now uses host.domain()
    • get_subdomain(): Now uses host.subdomain()
    • get_host(): Now returns Option<String> with proper string conversion
    • get_tld(): Now uses host.suffix_ref()

Type System:

  • Updated Python type stubs (pyfaup.pyi) to reflect new method signatures
  • Changed Url.host type from Optional[str] to Optional[Host]
  • Removed direct field accessors (subdomain, domain, suffix) from Url class in favor of method calls on Url.host object

Tests:

  • Updated existing tests to use new Host method calls
  • Added comprehensive tests for Host.domain(), Host.subdomain(), and Host.suffix() methods
  • Tests cover hostname, IPv4, and IPv6 scenarios with proper None handling

Breaking Changes

  • Python API: Url.host is now Optional[Host] instead of Optional[str]
  • Python API: Direct field access to subdomain, domain, suffix on Url no longer works - use method calls on Host instead
  • Python API: FaupCompat.get_host() now returns Option<String> instead of Option<&str> (but this should be transparent for python usage)

Testing

  • Rust library: All existing tests pass (40 tests)
  • Python bindings: Updated tests validate new functionality
  • Type checking: Python type stubs updated and validated

@qjerome qjerome merged commit bb57e50 into main Mar 3, 2026
19 checks passed
@qjerome qjerome deleted the refactor/host-api-improvements branch March 3, 2026 10:01
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant