Class: X::Space

Inherits:

Resource

Object
Resource
X::Space

show all

Extended by:: BatchFinders, Resources::BatchFinders

Defined in:: x-resources/lib/x/resources/space.rb

Overview

A live audio space

The space endpoints, but for buyers, take app-only authentication or OAuth 2.0 user context, not OAuth 1.0a, so a client that signs with OAuth 1.0a reads spaces with a copy that authenticates as the app, while the spaces and posts it reads hold the client, so that they act as the user.

Constant Summary collapse

FIELDS = Every public space field A minor release may add to it the fields the API adds, so that a lookup asks for them too; see Resource#hydrated? for what that means for a resource looked up with a list of fields of its own.

%w[created_at ended_at id is_ticketed lang participant_count scheduled_start started_at state
subscriber_count title updated_at].freeze

EXPANSIONS = Every expansion available on space endpoints A minor release may add to it the expansions the API adds, so that a lookup asks for them too; see Resource#hydrated? for what that means for a resource looked up with a list of expansions of its own.

%w[creator_id host_ids invited_user_ids speaker_ids topic_ids].freeze

Instance Attribute Summary collapse

#created_at ⇒ Time^? readonly
The time when the space was created.
#creator_id ⇒ Integer^? readonly
The identifier of the creator.
#ended_at ⇒ Time^? readonly
The time when the space ended.
#host_ids ⇒ Array<Integer> readonly
The identifiers of the hosts.
#invited_user_ids ⇒ Array<Integer> readonly
The identifiers of the invited users.
#lang ⇒ String^? readonly
The BCP 47 language tag.
#participant_count ⇒ Integer^? readonly
The number of participants.
#scheduled_start ⇒ Time^? readonly
The scheduled start time.
#speaker_ids ⇒ Array<Integer> readonly
The identifiers of the speakers.
#started_at ⇒ Time^? readonly
The time when the space started.
#state ⇒ String^? readonly
The state: live, scheduled, or ended.
#subscriber_count ⇒ Integer^? readonly
The number of subscribers.
#ticketed ⇒ Boolean^? readonly
Whether the space requires a ticket, the is_ticketed field.
#title ⇒ String^? readonly
The title.
#topic_ids ⇒ Array<Integer> readonly
The identifiers of the topics.
#updated_at ⇒ Time^? readonly
The time when the space was last updated.

Class Method Summary collapse

.default_params ⇒ Hash{String => Array<String>}
The default query parameters requesting every space field and expansion.
.find(id, client:, **params) {|problem| ... } ⇒ Resource^? extended from Resources::Finders
Look up a resource by identifier.
.find!(id, client:, **params) ⇒ Resource extended from Resources::Finders
Look up a resource by identifier, which must exist.
.find_all(ids, client:, concurrency: DEFAULT_CONCURRENCY, **params) {|problem| ... } ⇒ Array<Resource> extended from Resources::BatchFinders
Look up many resources by identifier, in parallel batches.
.find_all_by_creator(users, client:, concurrency: BatchFinders::DEFAULT_CONCURRENCY, **params) {|problem| ... } ⇒ Array<Space>
Look up the live and scheduled spaces many users created, in parallel batches.
.hydrate_all(resources, client:, concurrency: DEFAULT_CONCURRENCY, **params) {|problem| ... } ⇒ Array<Resource> extended from Resources::BatchFinders
Replace the resources that are not hydrated with the full resources.
.search(query, client:, **params) ⇒ Cursor
Search spaces by their titles.

Instance Method Summary collapse

#buyers(**params) ⇒ Cursor
The users who bought a ticket to this space.
#creator ⇒ User^?
The creator, resolved from the includes or as a stub holding only its identifier.
#hosts ⇒ Array<User>
The hosts, resolved from the includes or as stubs holding only their identifiers.
#invited_users ⇒ Array<User>
The invited users, from the includes or as stubs holding only their identifiers.
#posts(**params) ⇒ Cursor (also: #tweets)
The posts shared in this space.
#speakers ⇒ Array<User>
The speakers, from the includes or as stubs holding only their identifiers.
#ticketed? ⇒ Boolean
Check whether the space requires a ticket.
#topics ⇒ Array<Topic>
The topics, from the includes or as stubs holding only their identifiers.

Constructor Details

This class inherits a constructor from X::Resource

Instance Attribute Details

#created_at ⇒ `Time`^? (readonly)

The time when the space was created

Examples:

Get the creation time

space.created_at

Returns:

(Time, nil) —
the creation time

161	# File 'x-resources/lib/x/resources/space.rb', line 161 attribute :created_at, :time

#creator_id ⇒ `Integer`^? (readonly)

The identifier of the creator

Examples:

Get the creator identifier

space.creator_id

Returns:

(Integer, nil) —
the creator identifier

232	# File 'x-resources/lib/x/resources/space.rb', line 232 attribute :creator_id, :integer

#ended_at ⇒ `Time`^? (readonly)

The time when the space ended

Examples:

Get the end time

space.ended_at

Returns:

(Time, nil) —
the end time

177	# File 'x-resources/lib/x/resources/space.rb', line 177 attribute :ended_at, :time

#host_ids ⇒ `Array<Integer>` (readonly)

The identifiers of the hosts

Examples:

Get the host identifiers

space.host_ids

Returns:

(Array<Integer>) —
the host identifiers, empty if there are none

240	# File 'x-resources/lib/x/resources/space.rb', line 240 attribute :host_ids, :integers

#invited_user_ids ⇒ `Array<Integer>` (readonly)

The identifiers of the invited users

Examples:

Get the invited user identifiers

space.invited_user_ids

Returns:

(Array<Integer>) —
the invited user identifiers, empty if there are none

256	# File 'x-resources/lib/x/resources/space.rb', line 256 attribute :invited_user_ids, :integers

#lang ⇒ `String`^? (readonly)

The BCP 47 language tag

Examples:

Get the language

space.lang

Returns:

(String, nil) —
the language tag

153	# File 'x-resources/lib/x/resources/space.rb', line 153 attribute :lang

#participant_count ⇒ `Integer`^? (readonly)

The number of participants

Examples:

Get the participant count

space.participant_count

Returns:

(Integer, nil) —
the participant count

216	# File 'x-resources/lib/x/resources/space.rb', line 216 attribute :participant_count, :integer

#scheduled_start ⇒ `Time`^? (readonly)

The scheduled start time

Examples:

Get the scheduled start time

space.scheduled_start

Returns:

(Time, nil) —
the scheduled start time

185	# File 'x-resources/lib/x/resources/space.rb', line 185 attribute :scheduled_start, :time

#speaker_ids ⇒ `Array<Integer>` (readonly)

The identifiers of the speakers

Examples:

Get the speaker identifiers

space.speaker_ids

Returns:

(Array<Integer>) —
the speaker identifiers, empty if there are none

248	# File 'x-resources/lib/x/resources/space.rb', line 248 attribute :speaker_ids, :integers

#started_at ⇒ `Time`^? (readonly)

The time when the space started

Examples:

Get the start time

space.started_at

Returns:

(Time, nil) —
the start time

169	# File 'x-resources/lib/x/resources/space.rb', line 169 attribute :started_at, :time

#state ⇒ `String`^? (readonly)

The state: live, scheduled, or ended

Examples:

Get the state

space.state

Returns:

(String, nil) —
the state

145	# File 'x-resources/lib/x/resources/space.rb', line 145 attribute :state

#subscriber_count ⇒ `Integer`^? (readonly)

The number of subscribers

Examples:

Get the subscriber count

space.subscriber_count

Returns:

(Integer, nil) —
the subscriber count

224	# File 'x-resources/lib/x/resources/space.rb', line 224 attribute :subscriber_count, :integer

#ticketed ⇒ `Boolean`^? (readonly)

Whether the space requires a ticket, the is_ticketed field

Examples:

Check whether a space is ticketed

space.ticketed?

Returns:

(Boolean, nil) —
true if the space is ticketed

201	# File 'x-resources/lib/x/resources/space.rb', line 201 attribute :ticketed, :boolean, key: %w[is_ticketed]

#title ⇒ `String`^? (readonly)

The title

Examples:

Get the title

space.title

Returns:

(String, nil) —
the title

137	# File 'x-resources/lib/x/resources/space.rb', line 137 attribute :title

#topic_ids ⇒ `Array<Integer>` (readonly)

The identifiers of the topics

Examples:

Get the topic identifiers

space.topic_ids

Returns:

(Array<Integer>) —
the topic identifiers, empty if there are none

264	# File 'x-resources/lib/x/resources/space.rb', line 264 attribute :topic_ids, :integers

#updated_at ⇒ `Time`^? (readonly)

The time when the space was last updated

Examples:

Get the update time

space.updated_at

Returns:

(Time, nil) —
the update time

193	# File 'x-resources/lib/x/resources/space.rb', line 193 attribute :updated_at, :time

Class Method Details

.default_params ⇒ `Hash{String => Array<String>}`

The default query parameters requesting every space field and expansion

Examples:

Get the default parameters

X::Space.default_params["space.fields"]

Returns:

(Hash{String => Array<String>}) —
the default query parameters



89
90
91

# File 'x-resources/lib/x/resources/space.rb', line 89

def default_params
  {"space.fields" => FIELDS, "user.fields" => User::FIELDS, "topic.fields" => Topic::FIELDS, "expansions" => EXPANSIONS}
end

.find(id, client:, **params) {|problem| ... } ⇒ `Resource`^? Originally defined in module Resources::Finders

Look up a resource by identifier

Examples:

Look up a post by identifier

X::Post.find(1234567890, client: client)

Parameters:

id (String, Integer, Resource) —
the identifier, or a resource of this class
client (Object) —
the client used to make the request
params (Hash) —
query parameters merged over the default parameters; one that overrides a default field or expansion parameter to leave some out builds resources that are not hydrated, so hydrate fetches the rest

Yield Parameters:

problem (Problem) —
each problem the API reported, such as a resource that was not found

Returns:

(Resource, nil) —
the resource or nil if it was not found, whether the API answers 200 with no data or a 404 that reports the resource as not found

Raises:

(ArgumentError) —
if the identifier is not one, or is a resource of another class, before a request
(X::NotFound) —
if the API answers any other 404, such as one from a client pointed at the wrong host or API version

.find!(id, client:, **params) ⇒ `Resource` Originally defined in module Resources::Finders

Look up a resource by identifier, which must exist

The error it raises names the identifier looked up, whether the identifier or a resource was given. Its cause is the X::NotFound of a lookup the API answered with a 404 that reports the resource as not found.

Examples:

Look up a post by identifier

X::Post.find!(1234567890, client: client)

Parameters:

id (String, Integer, Resource) —
the identifier, or a resource of this class
client (Object) —
the client used to make the request
params (Hash) —
query parameters merged over the default parameters; one that overrides a default field or expansion parameter to leave some out builds resources that are not hydrated, so hydrate fetches the rest

Returns:

(Resource) —
the resource

Raises:

(ArgumentError) —
if the identifier is not one, or is a resource of another class, before a request
(MissingResource) —
if the resource was not found, whether the API answers 200 with no data or a 404 that reports the resource as not found
(X::NotFound) —
if the API answers any other 404, such as one from a client pointed at the wrong host or API version

.find_all(ids, client:, concurrency: DEFAULT_CONCURRENCY, **params) {|problem| ... } ⇒ `Array<Resource>` Originally defined in module Resources::BatchFinders

Look up many resources by identifier, in parallel batches

The resources come back in the order of the identifiers they were asked for by, whatever order the batches were answered in, one for each identifier that was found, so an identifier asked for twice comes back twice, as hydrate_all keeps a resource it is given twice. Each identifier is asked for once, however often it is given.

Examples:

Look up many posts by identifier, reporting the ones that were not found

X::Post.find_all([1234567890, 1234567891], client: client) { |problem| warn problem.detail }

Look up many posts one batch at a time, to spend a rate limit more slowly

X::Post.find_all(ids, client: client, concurrency: 1)

Parameters:

ids (Array<String, Integer, Resource>) —
the identifiers, or resources of this class
client (Object) —
the client used to make the requests
concurrency (Integer) (defaults to: DEFAULT_CONCURRENCY) —
the number of batches looked up at once, four by default, which must be at least one; each is a request of up to 100 identifiers, so a lower number spends a rate limit more slowly
params (Hash) —
query parameters merged over the default parameters; one that overrides a default field or expansion parameter to leave some out builds resources that are not hydrated, so hydrate fetches the rest

Yield Parameters:

problem (Problem) —
each problem the API reported, such as an identifier that was not found

Returns:

(Array<Resource>) —
the resources that were found, one for each identifier that names one, frozen

Raises:

(ArgumentError) —
if the concurrency is less than one
(ArgumentError) —
if an identifier is not one, or is a resource of another class, before a request

.find_all_by_creator(users, client:, concurrency: BatchFinders::DEFAULT_CONCURRENCY, **params) {|problem| ... } ⇒ `Array<Space>`

Look up the live and scheduled spaces many users created, in parallel batches

The API returns the spaces of up to 100 users at a time, in one response without pages, so the users are looked up that many at a time.

Examples:

Print the spaces two users created

X::Space.find_all_by_creator([7505382, 783214], client: client).each { |space| puts space.title }

Parameters:

users (Array<User, String, Integer>) —
the users who created the spaces, or their identifiers
client (Object) —
the client used to make the requests
concurrency (Integer) (defaults to: BatchFinders::DEFAULT_CONCURRENCY) —
the number of batches looked up at once, which must be at least one
params (Hash) —
query parameters merged over the default parameters

Yield Parameters:

problem (Problem) —
each problem the API reported

Returns:

(Array<Space>) —
the spaces, frozen, empty if the users created none

Raises:

(ArgumentError) —
if a user is not a user or the identifier of one, or the concurrency is less than one, before a request

# File 'x-resources/lib/x/resources/space.rb', line 125

def self.find_all_by_creator(users, client:, concurrency: BatchFinders::DEFAULT_CONCURRENCY, **params, &)
  ids = users.map { |user| Utils.id_of(user, User) }
  spaces = lookup_in_batches("spaces/by/creator_ids", :user_ids, ids, client:, concurrency:, **params, &) #: Array[Space]
  spaces.freeze
end

.hydrate_all(resources, client:, concurrency: DEFAULT_CONCURRENCY, **params) {|problem| ... } ⇒ `Array<Resource>` Originally defined in module Resources::BatchFinders

Replace the resources that are not hydrated with the full resources

A resource that hydrate would look up is looked up, which is a stub and also a resource a response included without every field, so what comes back is hydrated throughout. A resource that was not found is dropped, as is nil, which a reference to no resource reads as, such as the author of a post whose response named none, and a hydrated resource is kept as it is, so resources that are all hydrated need no lookup. What was found is stored in each original, so hydrating one of them afterwards costs no request, unless params override a default field or expansion parameter: what such a lookup found is not the full resource, so it is returned without being stored, and hydrating an original fetches the full resource. A resource that holds what hydrate returns, because hydrate or an earlier hydrate_all stored it, is replaced with that, and looked up again by no request, since the API bills each resource a lookup returns.

Examples:

Look up every field of the authors of posts, the ones a search included among them

X::User.hydrate_all(posts.map(&:author), client: client)

Expand only the authors a search did not include, which the API bills for alone

X::User.hydrate_all(posts.filter_map(&:author).select(&:stub?), client: client)

Parameters:

resources (Array<Resource, nil>) —
the resources, some of which may not be hydrated, and some nil
client (Object) —
the client used to make the requests
concurrency (Integer) (defaults to: DEFAULT_CONCURRENCY) —
the number of batch lookups made at once, four by default, which must be at least one
params (Hash) —
query parameters merged over the default parameters; one that overrides a default field or expansion parameter to leave some out builds resources that are not hydrated, so hydrate fetches the rest

Yield Parameters:

problem (Problem) —
each problem the API reported, such as a resource that was not found

Returns:

(Array<Resource>) —
the resources, in order, with the ones that were not hydrated replaced, frozen

Raises:

(ArgumentError) —
if the concurrency is less than one
(ArgumentError) —
if a resource is not of this class, which a lookup of its identifier would find another resource for, before a request

.search(query, client:, **params) ⇒ `Cursor`

Search spaces by their titles

The API returns the matching spaces in one response, of up to 100 spaces.

Examples:

Print the live spaces about Ruby

X::Space.search("ruby", client: client, state: "live").each { |space| puts space.title }

Parameters:

query (String) —
the search query
client (Object) —
the client used to make the request
params (Hash) —
query parameters merged over the default parameters, such as state: live or scheduled

Returns:

(Cursor) —
a cursor over the matching spaces



104
105
106

# File 'x-resources/lib/x/resources/space.rb', line 104

def search(query, client:, **params)
  Cursor.__send__(:build, self, "spaces/search", client:, params: {query:, max_results: MAX_RESULTS}.merge(params), app_only: true)
end

Instance Method Details

#buyers(**params) ⇒ `Cursor`

The users who bought a ticket to this space

The authenticated user must have created the space. The endpoint takes only OAuth 2.0 user context, which the object layer cannot route around, so a client that signs with OAuth 1.0a, or authenticates as the app, is refused.

Examples:

Print the buyers of a ticketed space

space.buyers.each { |user| puts user.username }

Parameters:

params (Hash) —
query parameters merged over the default parameters

Returns:

(Cursor) —
a cursor over the buyers

327	# File 'x-resources/lib/x/resources/space.rb', line 327 def buyers(params) = cursor(User, "spaces/#{id}/buyers", max_results: MAX_RESULTS, params)

#creator ⇒ `User`^?

The creator, resolved from the includes or as a stub holding only its identifier

Examples:

Get the creator's username

space.creator.username

Returns:

(User, nil) —
the creator

272	# File 'x-resources/lib/x/resources/space.rb', line 272 reference :creator, :User, key: %w[creator_id]

#hosts ⇒ `Array<User>`

The hosts, resolved from the includes or as stubs holding only their identifiers

Examples:

Get the hosts

space.hosts

Returns:

(Array<User>) —
the hosts

280	# File 'x-resources/lib/x/resources/space.rb', line 280 references :hosts, :User, key: %w[host_ids]

#invited_users ⇒ `Array<User>`

The invited users, from the includes or as stubs holding only their identifiers

Examples:

Get the invited users

space.invited_users

Returns:

(Array<User>) —
the invited users

296	# File 'x-resources/lib/x/resources/space.rb', line 296 references :invited_users, :User, key: %w[invited_user_ids]

#posts(**params) ⇒ `Cursor` Also known as: tweets

The posts shared in this space

Examples:

Print the shared posts

space.posts.each { |post| puts post.text }

Parameters:

params (Hash) —
query parameters merged over the default parameters

Returns:

(Cursor) —
a cursor over the posts



313
314
315

# File 'x-resources/lib/x/resources/space.rb', line 313

def posts(**params)
  cursor(Post, "spaces/#{id}/tweets", max_results: MAX_RESULTS, app_only: true, **params)
end

#speakers ⇒ `Array<User>`

The speakers, from the includes or as stubs holding only their identifiers

Examples:

Get the speakers

space.speakers

Returns:

(Array<User>) —
the speakers

288	# File 'x-resources/lib/x/resources/space.rb', line 288 references :speakers, :User, key: %w[speaker_ids]

#ticketed? ⇒ `Boolean`

Check whether the space requires a ticket

Examples:

Check whether a space is ticketed

space.ticketed?

Returns:

(Boolean) —
true if the space is ticketed

# File 'x-resources/lib/x/resources/space.rb', line 203

#topics ⇒ `Array<Topic>`

The topics, from the includes or as stubs holding only their identifiers

Examples:

Get the names of the topics

space.topics.map(&:name)

Returns:

(Array<Topic>) —
the topics

304	# File 'x-resources/lib/x/resources/space.rb', line 304 references :topics, :Topic, key: %w[topic_ids]

Class: X::Space

Overview

Constant Summary collapse

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

Instance Attribute Details

#created_at ⇒ Time? (readonly)

Examples:

Get the creation time

#creator_id ⇒ Integer? (readonly)

Examples:

Get the creator identifier

#ended_at ⇒ Time? (readonly)

Examples:

Get the end time

#host_ids ⇒ Array<Integer> (readonly)

Examples:

Get the host identifiers

#invited_user_ids ⇒ Array<Integer> (readonly)

Examples:

Get the invited user identifiers

#lang ⇒ String? (readonly)

Examples:

Get the language

#participant_count ⇒ Integer? (readonly)

Examples:

Get the participant count

#scheduled_start ⇒ Time? (readonly)

Examples:

Get the scheduled start time

#speaker_ids ⇒ Array<Integer> (readonly)

Examples:

Get the speaker identifiers

#started_at ⇒ Time? (readonly)

Examples:

Get the start time

#state ⇒ String? (readonly)

Examples:

Get the state

#subscriber_count ⇒ Integer? (readonly)

Examples:

Get the subscriber count

#ticketed ⇒ Boolean? (readonly)

Examples:

Check whether a space is ticketed

#title ⇒ String? (readonly)

Examples:

Get the title

#topic_ids ⇒ Array<Integer> (readonly)

Examples:

Get the topic identifiers

#updated_at ⇒ Time? (readonly)

Examples:

Get the update time

Class Method Details

.default_params ⇒ Hash{String => Array<String>}

Examples:

Get the default parameters

.find(id, client:, **params) {|problem| ... } ⇒ Resource? Originally defined in module Resources::Finders

Examples:

Look up a post by identifier

.find!(id, client:, **params) ⇒ Resource Originally defined in module Resources::Finders

Examples:

Look up a post by identifier

.find_all(ids, client:, concurrency: DEFAULT_CONCURRENCY, **params) {|problem| ... } ⇒ Array<Resource> Originally defined in module Resources::BatchFinders

Examples:

Look up many posts by identifier, reporting the ones that were not found

Look up many posts one batch at a time, to spend a rate limit more slowly

.find_all_by_creator(users, client:, concurrency: BatchFinders::DEFAULT_CONCURRENCY, **params) {|problem| ... } ⇒ Array<Space>

Examples:

Print the spaces two users created

.hydrate_all(resources, client:, concurrency: DEFAULT_CONCURRENCY, **params) {|problem| ... } ⇒ Array<Resource> Originally defined in module Resources::BatchFinders

Examples:

Look up every field of the authors of posts, the ones a search included among them

Expand only the authors a search did not include, which the API bills for alone

.search(query, client:, **params) ⇒ Cursor

Examples:

Print the live spaces about Ruby

#created_at ⇒ `Time`^? (readonly)

#creator_id ⇒ `Integer`^? (readonly)

#ended_at ⇒ `Time`^? (readonly)

#host_ids ⇒ `Array<Integer>` (readonly)

#invited_user_ids ⇒ `Array<Integer>` (readonly)

#lang ⇒ `String`^? (readonly)

#participant_count ⇒ `Integer`^? (readonly)

#scheduled_start ⇒ `Time`^? (readonly)

#speaker_ids ⇒ `Array<Integer>` (readonly)

#started_at ⇒ `Time`^? (readonly)

#state ⇒ `String`^? (readonly)

#subscriber_count ⇒ `Integer`^? (readonly)

#ticketed ⇒ `Boolean`^? (readonly)

#title ⇒ `String`^? (readonly)

#topic_ids ⇒ `Array<Integer>` (readonly)

#updated_at ⇒ `Time`^? (readonly)

.default_params ⇒ `Hash{String => Array<String>}`

.find(id, client:, **params) {|problem| ... } ⇒ `Resource`^? Originally defined in module Resources::Finders

.find!(id, client:, **params) ⇒ `Resource` Originally defined in module Resources::Finders

.find_all(ids, client:, concurrency: DEFAULT_CONCURRENCY, **params) {|problem| ... } ⇒ `Array<Resource>` Originally defined in module Resources::BatchFinders

.find_all_by_creator(users, client:, concurrency: BatchFinders::DEFAULT_CONCURRENCY, **params) {|problem| ... } ⇒ `Array<Space>`

.hydrate_all(resources, client:, concurrency: DEFAULT_CONCURRENCY, **params) {|problem| ... } ⇒ `Array<Resource>` Originally defined in module Resources::BatchFinders

.search(query, client:, **params) ⇒ `Cursor`

#buyers(**params) ⇒ `Cursor`

#creator ⇒ `User`^?

#hosts ⇒ `Array<User>`

#invited_users ⇒ `Array<User>`

#posts(**params) ⇒ `Cursor` Also known as: tweets

#speakers ⇒ `Array<User>`

#ticketed? ⇒ `Boolean`

#topics ⇒ `Array<Topic>`