Module: X::Uploader::Account

Extended by:
Account
Included in:
Account
Defined in:
x-uploader/lib/x/uploader/account.rb

Overview

Uploads profile images and banners to the X API v1.1

Its methods can be called on the module, or on an instance of a class that includes it, which gains its public methods alone. They post to the API v1.1 endpoint with the client they are given, which keeps the connection it holds to the host open for the requests that follow, rather than with a copy of it. The endpoint is resolved against the base URL of the client, in place of the version it names, so it is reached at the host the client sends its other requests to, which its credentials are sent to, whether that is api.x.com, api.twitter.com, or a proxy of the API.

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.update_profile_banner(media, client:, width: nil, height: nil, offset_left: nil, offset_top: nil) ⇒ void

This method returns an undefined value.

Update the authenticating user's profile banner

It returns nil, whatever the client answers with, since the endpoint answers with no content once the banner is updated.

Examples:

Update profile banner from a file

Uploader::Account.update_profile_banner("banner.png", client: client)

Update profile banner with dimensions

Uploader::Account.update_profile_banner("banner.png", client: client, width: 1500, height: 500)

Parameters:

  • media (String, Pathname, IO, StringIO) —

    the path to the image, or an IO that reads it, which is read from its start, as the media of an upload is

  • client (Client) —

    the X API client

  • width (Integer, nil) (defaults to: nil) —

    the width of the region of the image to use, in pixels, of at least 1

  • height (Integer, nil) (defaults to: nil) —

    the height of the region of the image to use, in pixels, of at least 1

  • offset_left (Integer, nil) (defaults to: nil) —

    the pixels by which the region is offset from the left, of at least 0

  • offset_top (Integer, nil) (defaults to: nil) —

    the pixels by which the region is offset from the top, of at least 0

Raises:

  • (InvalidMedia) —

    if the file does not exist

  • (ArgumentError) —

    if the media is neither a path nor an IO, or a width, height, or offset is neither nil nor an Integer of the pixels it takes

  • (InvalidMedia) —

    if the media cannot be read, is empty, which holds nothing to upload, or is larger than the 5 megabytes X takes of a profile banner

  • (InvalidMediaType) —

    if the media does not begin with the signature of a GIF, a JPEG, or a PNG, whatever its file is named



85
86
87
88
89
90
91
 
# File 'x-uploader/lib/x/uploader/account.rb', line 85

def update_profile_banner(media, client:, width: nil, height: nil, offset_left: nil, offset_top: nil)
  Validator.validate_banner_region!(width:, height:, offset_left:, offset_top:)
  source = Source.for(media)
  Validator.validate_profile_image!(source, Validator::MAX_PROFILE_BANNER_BYTES, "a profile banner")
  Multipart.post(client, PROFILE_BANNER_URL, "banner", source.content, width:, height:, offset_left:, offset_top:)
  nil
end

.update_profile_image(media, client:) ⇒ void

This method returns an undefined value.

Update the authenticating user's profile image

It returns nil, whatever the client answers with, as #update_profile_banner does: the API v1.1 answers with the user in its own shape, keyed as v1.1 keys it, which no object of these gems reads, since an X::User of x-objects reads the users of the API v2 alone. Look the user up with the API v2 to read the image it now has.

Examples:

Update profile image from a file

Uploader::Account.update_profile_image("avatar.png", client: client)

Update profile image from an image held in memory

Uploader::Account.update_profile_image(StringIO.new(png), client: client)

Parameters:

  • media (String, Pathname, IO, StringIO) —

    the path to the image, or an IO that reads it, which is read from its start, as the media of an upload is

  • client (Client) —

    the X API client

Raises:

  • (InvalidMedia) —

    if the file does not exist

  • (ArgumentError) —

    if the media is neither a path nor an IO

  • (InvalidMedia) —

    if the media cannot be read, is empty, which holds nothing to upload, or is larger than the 700 kilobytes the API takes of a profile image

  • (InvalidMediaType) —

    if the media does not begin with the signature of a GIF, a JPEG, or a PNG, whatever its file is named



53
54
55
56
57
58
 
# File 'x-uploader/lib/x/uploader/account.rb', line 53

def update_profile_image(media, client:)
  source = Source.for(media)
  Validator.validate_profile_image!(source, Validator::MAX_PROFILE_IMAGE_BYTES, "a profile image")
  Multipart.post(client, PROFILE_IMAGE_URL, "image", source.content)
  nil
end

Instance Method Details

#update_profile_banner(media, client:, width: nil, height: nil, offset_left: nil, offset_top: nil) ⇒ void

This method returns an undefined value.

Update the authenticating user's profile banner

It returns nil, whatever the client answers with, since the endpoint answers with no content once the banner is updated.

Examples:

Update profile banner from a file

Uploader::Account.update_profile_banner("banner.png", client: client)

Update profile banner with dimensions

Uploader::Account.update_profile_banner("banner.png", client: client, width: 1500, height: 500)

Parameters:

  • media (String, Pathname, IO, StringIO) —

    the path to the image, or an IO that reads it, which is read from its start, as the media of an upload is

  • client (Client) —

    the X API client

  • width (Integer, nil) (defaults to: nil) —

    the width of the region of the image to use, in pixels, of at least 1

  • height (Integer, nil) (defaults to: nil) —

    the height of the region of the image to use, in pixels, of at least 1

  • offset_left (Integer, nil) (defaults to: nil) —

    the pixels by which the region is offset from the left, of at least 0

  • offset_top (Integer, nil) (defaults to: nil) —

    the pixels by which the region is offset from the top, of at least 0

Raises:

  • (InvalidMedia) —

    if the file does not exist

  • (ArgumentError) —

    if the media is neither a path nor an IO, or a width, height, or offset is neither nil nor an Integer of the pixels it takes

  • (InvalidMedia) —

    if the media cannot be read, is empty, which holds nothing to upload, or is larger than the 5 megabytes X takes of a profile banner

  • (InvalidMediaType) —

    if the media does not begin with the signature of a GIF, a JPEG, or a PNG, whatever its file is named



85
86
87
88
89
90
91
 
# File 'x-uploader/lib/x/uploader/account.rb', line 85

def update_profile_banner(media, client:, width: nil, height: nil, offset_left: nil, offset_top: nil)
  Validator.validate_banner_region!(width:, height:, offset_left:, offset_top:)
  source = Source.for(media)
  Validator.validate_profile_image!(source, Validator::MAX_PROFILE_BANNER_BYTES, "a profile banner")
  Multipart.post(client, PROFILE_BANNER_URL, "banner", source.content, width:, height:, offset_left:, offset_top:)
  nil
end

#update_profile_image(media, client:) ⇒ void

This method returns an undefined value.

Update the authenticating user's profile image

It returns nil, whatever the client answers with, as #update_profile_banner does: the API v1.1 answers with the user in its own shape, keyed as v1.1 keys it, which no object of these gems reads, since an X::User of x-objects reads the users of the API v2 alone. Look the user up with the API v2 to read the image it now has.

Examples:

Update profile image from a file

Uploader::Account.update_profile_image("avatar.png", client: client)

Update profile image from an image held in memory

Uploader::Account.update_profile_image(StringIO.new(png), client: client)

Parameters:

  • media (String, Pathname, IO, StringIO) —

    the path to the image, or an IO that reads it, which is read from its start, as the media of an upload is

  • client (Client) —

    the X API client

Raises:

  • (InvalidMedia) —

    if the file does not exist

  • (ArgumentError) —

    if the media is neither a path nor an IO

  • (InvalidMedia) —

    if the media cannot be read, is empty, which holds nothing to upload, or is larger than the 700 kilobytes the API takes of a profile image

  • (InvalidMediaType) —

    if the media does not begin with the signature of a GIF, a JPEG, or a PNG, whatever its file is named



53
54
55
56
57
58
 
# File 'x-uploader/lib/x/uploader/account.rb', line 53

def update_profile_image(media, client:)
  source = Source.for(media)
  Validator.validate_profile_image!(source, Validator::MAX_PROFILE_IMAGE_BYTES, "a profile image")
  Multipart.post(client, PROFILE_IMAGE_URL, "image", source.content)
  nil
end