Fix #2370: Add allowed_path_traversal_elements option to file_path()

[Ayushmann13479]

What does this change

Adds a new optional parameter allowed_path_traversal_elements to file_path() that allows path-traversal segments (e.g. '.' and '..') to be randomly included as generated directory components.

What was wrong

file_path() had no way to generate paths containing path-traversal elements like '.' or '..', which are useful for testing directory traversal attack detection and input sanitization.

How this fixes it

Added a new allowed_path_traversal_elements parameter (default None, preserving existing behavior). When provided as a sequence (e.g. ['.', '..']), each directory segment in the generated path has a chance of being randomly replaced with one of these traversal elements instead of a regular word.

Fixes #2370

AI Assistance Disclosure (REQUIRED)

• If AI tools were used, I have disclosed which ones, and fully reviewed and verified their output.

I used Claude (Anthropic) to help draft the implementation and docstring. I reviewed, understood, and verified the logic and tested it manually before submitting.

Checklist

• I have read the documentation about CONTRIBUTING
• I have read the documentation about Coding style
• I have run make lint

[Ayushmann13479]

Hi @maintainers, just checking in on this PR whenever you get a chance to review.

All checks have passed and there are no conflicts with the base branch. Happy to make any changes if needed — let me know if you'd like the approach adjusted or have any feedback on the implementation.

Thanks for maintaining this great library!

[fcurella]

I think this is a good feature to have, but we'll also need some unit tests

[fcurella]

what is the use case for having this as strings, rather than a single boolean? What other path traversal elements are you thinking of, other than . and ..?

[Ayushmann13479]

Hi @fcurella, thanks for the review!

Regarding the use case for Sequence[str] over boolean:

• A boolean would only allow toggling on/off with a fixed set (['.', '..'])
• Sequence[str] gives the caller full control — e.g. they could pass
  ['..', '...', '%2e%2e'] to test URL-encoded traversal sequences
  or OS-specific variants like ['..\'] on Windows
• This makes it more useful for security testing scenarios as described
  in issue Feature request: Add other file_path options #2370

I'll add unit tests now and push an update shortly.

[Ayushmann13479]

Hi @fcurella, thanks for the review!

Regarding Sequence[str] over boolean: a boolean would only allow
toggling on/off a fixed set (['.', '..']). Sequence[str] gives
the caller full control — e.g. ['..', '%2e%2e'] for URL-encoded
traversal, or OS-specific variants like ['..\'] on Windows.
More useful for security testing as described in #2370.

I've now added unit tests covering: default behavior, single
traversal element, combined traversal elements, and Windows
file system compatibility.

[fcurella]

Thank you!