api: Add bindings for fetching user avatar.

[PieterCK]

Prep PR for: zulip/zulip#32495

Reasonings for a couple decisions I made when working on this:

• I saw that we already have a get_user_by_id for the /user/{user_id}, so I opted to name the methods something likeget_avatar_url_by_id.
• It's also split into get_avatar_url_by_id and get_avatar_url_by_email instead of a method that accepts a parameter like user_id_or_email: str | int since we've deliberately split the avatar/ endpoint in the server.

CZO: #api documentation > Python examples that require importing other modules. @ 💬

Self-review checklist

• Self-reviewed the changes for clarity and maintainability
  (variable names, code reuse, readability, etc.).

Communicate decisions, questions, and potential concerns.

• Explains differences from previous plans (e.g., issue description).
• Highlights technical choices and bugs encountered.
• Calls out remaining decisions and concerns.
• Automated tests verify logic where appropriate.

Individual commits are ready for review (see commit discipline).

• Each commit is a coherent idea.
• Commit message(s) explain reasoning and motivation for changes.

Completed manual review and testing of the following:

• Visual appearance of the changes.
• Responsiveness and internationalization.
• Strings and tooltips.
• End-to-end functionality of buttons, interactions and flows.
• Corner cases, error conditions, and easily imagined bugs.

[PieterCK]

Is there a case where we should allow this to be empty string?

[PieterCK]

@prakhar1144 -- Could you please review this one?

[chrisbobbe]

How is authentication normally handled in the bindings? We should take care not to follow off-realm redirects with auth headers included. I'm not sure whether this revision handles that correctly or not.

[PieterCK]

How is authentication normally handled in the bindings?

The Client class parses the user credentials from a .zuliprc file.

We should take care not to follow off-realm redirects with auth headers included.

The get_avatar_url_by_* bindings only return the avatar URL -- they extract the redirect URL from the response header's "Location" field. There's also a condition to set allow_redirect=False if it's a redirect response, and it's one of the redirect endpoints (only avatar endpoints as of now), so there shouldn't be any actual redirects when the bindings call the avatar endpoints.

I've included an examples/get-user-avatar example for manual testing! To test it, simply run a Zulip dev server, get a .zuliprc file from a generic bot or a user, and run ../examples/get-user-avatar --email=<email> --user_id=<id> in the CLI.