refactor: implement browser preferences types and validation

[ArthurRodrigues4433]

Pull Request

Description

Esta PR refatora o sistema de preferências do browser (ChromiumOptions) para adicionar tipagem forte, validação e melhor tratamento de erros. As principais mudanças incluem:

• Criação de TypedDicts para BrowserPreferences, DownloadPreferences e ProfilePreferences, garantindo tipo seguro e autocomplete em IDEs.
• Introdução de PREFERENCE_SCHEMA para validação de caminhos e tipos de valores.
• Métodos _validate_pref_path e _validate_pref_value adicionados para checagem rigorosa de caminhos e tipos de preferências.
• Atualização de getters e setters (browser_preferences, prompt_for_download, password_manager_enabled, open_pdf_externally) para refletirem tipagem correta e retornarem Optional quando apropriado.
• Melhor tratamento de erros com mensagens descritivas para WrongPrefsDict, InvalidPreferencePath e InvalidPreferenceValue.
• Adição de testes unitários completos cobrindo validação, merges e acesso seguro às preferências.
• Pequenas melhorias no temp_dir_manager e no tratamento de argumentos do ChromiumOptions.

Related Issue(s)

#289

Type of Change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation update
• Refactoring (melhoria interna, tipagem e validação)
• Performance improvement
• Tests (adição e correção de testes unitários)

How Has This Been Tested?

• Testes unitários cobrindo:
  • Validação de caminhos de preferências válidos e inválidos
  • Validação de tipos de valores corretos e incorretos
  • Merge correto de preferências existentes
  • Acesso seguro a preferências existentes e inexistentes
• Todos os testes existentes continuam passando.
• Cobertura de código: 98%

# Exemplo de uso do novo sistema de tipos:
browser_preferences: BrowserPreferences = {
    'download': {
        'default_directory': 'C:/Downloads',
        'prompt_for_download': True
    },
    'profile': {
        'password_manager_enabled': True
    },
    'credentials_enable_service': True
}

Testing Checklist

• Unit tests added/updated
• Integration tests added/updated
• All existing tests pass

Screenshots

Implementation Details

• Introduzido BrowserPreferences como TypedDict
• Implementado PREFERENCE_SCHEMA para validação estrutural
• Adicionados métodos de validação de caminhos e valores
• Propriedades atualizadas com Optional quando necessário
• Melhor documentação interna e mensagens de erro claras
• Correção de comando de formatação no pyproject.toml

API Changes

Não há mudanças na API pública. As alterações são internas e mantêm compatibilidade total com o código existente.

Additional Info

• O código segue padrões PEP8 e padrões do projeto.
• Tipagem e validação agora permitem autocompletar e reduzem erros em tempo de execução.
• Todas as preferências existentes foram mantidas.

Checklist before requesting a review

• My code follows the style guidelines of this project
• I have performed a self-review of my code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes
• I have run poetry run task lint and fixed any issues
• I have run poetry run task test and all tests pass
• My commits follow the conventional commits style

Summary by CodeRabbit

Release Notes

• New Features

  • Added validation for browser preferences to enforce correct types and paths; invalid preferences now raise InvalidPreferencePath or InvalidPreferenceValue exceptions.

• Bug Fixes

  • Properties prompt_for_download, password_manager_enabled, and open_pdf_externally now correctly return Optional[bool] to reflect possible absence of values.

• Tests

  • Added comprehensive test coverage for browser preference validation and handling.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[thalissonvs]

Opa, tudo bem? precisa de alguma ajuda com os erros?

[ArthurRodrigues4433]

Sim, Está passando nos testes locais mas sempre falha nos teste aqui do GitHub!

[thalissonvs]

Hello @ArthurRodrigues4433, obrigado pela contribuição e perdao pela demora. Consegue dar uma olhada nos conflitos?

[coderabbitai]

📝 Walkthrough

Walkthrough

This change implements type-safe browser preference management through TypedDict-based structures, validation schemas, and exception types. The ChromiumOptions class gains preference path/value validation methods and updated return types, while new exception classes handle validation errors.

Changes

Cohort / File(s)	Summary
Type System Foundation pydoll/browser/preference_types.py, pydoll/exceptions.py	Introduces BrowserPreferences, ProfilePreferences, DownloadPreferences, ContentSettingValues as TypedDicts; adds PREFERENCE_SCHEMA for runtime validation; defines new exception classes InvalidPreferencePath and InvalidPreferenceValue.
Interface Updates pydoll/browser/interfaces.py	Updates Options.browser_preferences property return type from dict to BrowserPreferences.
Options Implementation pydoll/browser/options.py	Adds preference validation via _validate_pref_path and _validate_pref_value static methods; updates browser_preferences getter/setter to return/accept BrowserPreferences with validation and merging; changes prompt_for_download, password_manager_enabled, open_pdf_externally return types to Optional[bool]; updates _get_pref_path and _set_pref_path to validate before operations; adds side-effect to password_manager_enabled setter.
Type Annotations pydoll/browser/managers/temp_dir_manager.py	Adds explicit type hints (list[str]) to local variables in handle_cleanup_error method.
Build Configuration pyproject.toml	Changes task commands from semicolon to logical AND operators for sequential execution control.
Test Coverage tests/test_browser/test_browser_preferences.py	Adds comprehensive test suite covering preference path validation, value validation, setting/merging preferences, getter behavior, and error handling scenarios.

Sequence Diagrams

sequenceDiagram
    participant Client
    participant ChromiumOptions
    participant Validator
    participant Storage

    Client->>ChromiumOptions: set browser_preferences(prefs)
    ChromiumOptions->>Validator: _validate_pref_path(path)
    alt Invalid Path
        Validator-->>ChromiumOptions: InvalidPreferencePath
        ChromiumOptions-->>Client: Error
    else Valid Path
        ChromiumOptions->>Validator: _validate_pref_value(path, value)
        alt Invalid Value
            Validator-->>ChromiumOptions: InvalidPreferenceValue
            ChromiumOptions-->>Client: Error
        else Valid Value
            ChromiumOptions->>Storage: merge/update preferences
            Storage-->>ChromiumOptions: Success
            ChromiumOptions-->>Client: Success
        end
    end

Loading

sequenceDiagram
    participant Client
    participant ChromiumOptions
    participant Validator
    participant Storage

    Client->>ChromiumOptions: get browser_preferences
    ChromiumOptions->>ChromiumOptions: _get_pref_path(path)
    ChromiumOptions->>Validator: _validate_pref_path(path)
    alt Invalid Path
        Validator-->>ChromiumOptions: InvalidPreferencePath
        ChromiumOptions-->>Client: Error
    else Valid Path
        ChromiumOptions->>Storage: retrieve value
        Storage-->>ChromiumOptions: value
        ChromiumOptions-->>Client: BrowserPreferences
    end

Loading

Estimated Code Review Effort

🎯 3 (Moderate) | ⏱️ ~22 minutes

Possibly Related Issues

• Issue #289: Directly implements TypedDict-based BrowserPreferences, preference validation schema, new exception classes (InvalidPreferencePath, InvalidPreferenceValue), and ChromiumOptions signature/behavior updates with preference path and value validation.

Poem

🐰 Preferences now validated with care,
Types and schemas everywhere!
Paths and values pass the test,
Browser options at their best!
No more chaos, just delight,
Type safety burning bright! ✨

🚥 Pre-merge checks | ✅ 3 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 75.68% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The PR title clearly describes the main change: implementing browser preferences types and validation, which aligns with the core refactoring objective of adding TypedDicts, PREFERENCE_SCHEMA, and validation methods.
Description check	✅ Passed	The PR description is comprehensive and covers all required template sections including Description, Related Issues, Type of Change, Testing approach, Implementation Details, API Changes, and the complete checklist.
Merge Conflict Detection	✅ Passed	✅ No merge conflicts detected when merging into main

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

Tip

Issue Planner is now in beta. Read the docs and try it out! Share your feedback on Discord.

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 2

🤖 Fix all issues with AI agents

In `@pydoll/browser/options.py`:
- Around line 137-140: The check using preferences.get('prefs') in options.py is
only truthy and won’t catch keys with falsy values; change it to detect the
presence of the top-level key instead (e.g., use "'prefs' in preferences") so
that the WrongPrefsDict raised from this block (the same exception class
referenced) triggers whenever a top-level 'prefs' key exists, even if its value
is {} or None; keep the existing error message and surrounding logic unchanged.

In `@pydoll/browser/preference_types.py`:
- Around line 6-29: The TypedDicts DownloadPreferences and ProfilePreferences
are declared as fully required but _set_pref_path and the browser_preferences
property populate partial dicts (e.g., only prompt_for_download or only
password_manager_enabled); change DownloadPreferences and ProfilePreferences to
be partial by adding total=False (i.e., declare "class
DownloadPreferences(TypedDict, total=False)" and "class
ProfilePreferences(TypedDict, total=False)") so their types match runtime
construction and callers of browser_preferences won't expect missing keys.

[ArthurRodrigues4433]

Olá @thalissonvs, sem problema!
Conflitos resolvidos, testei e fiz o push. Fico no aguardo da sua revisão.