API Objects¶

The classes and functions documented on this page constitute the public API to the okcupyd library.

`User`¶

User serves as the primary entry point to the okcupyd library. Most of the objects mentioned on this page are accessible in some way or another from instances of User.

class okcupyd.user.User(session=None)[source]¶

Encapsulate a logged in okcupid user.

classmethod from_credentials(username, password)[source]¶

Parameters:	username (str) – The username to log in with. password (str) – The password to log in with.

__init__(session=None)[source]¶

Parameters:	session (`Session`) – The session which will be used for interacting with okcupid.com If none is provided, one will be instantiated automatically with the credentials in `settings`

profile = None¶: A Profile object belonging to the logged in user.

inbox = None¶: A Fetchable of MessageThread objects corresponding to messages that are currently in the user’s inbox.

outbox = None¶: A Fetchable of MessageThread objects corresponding to messages that are currently in the user’s outbox.

drafts = None¶: A Fetchable of MessageThread objects corresponding to messages that are currently in the user’s drafts folder.

visitors = None¶: A Fetchable of Profile objects of okcupid.com users that have visited the user’s profile.

questions = None¶: A Questions object that is instantiated with the owning User instance’s session.

attractiveness_finder = None¶: An _AttractivenessFinder object that is instantiated with the owning User instance’s session.

photo = None¶: A PhotoUploader that is instantiated with the owning User instance’s session.

location_cache = None¶: A LocationQueryCache instance

get_profile(username)[source]¶

Get the Profile associated with the supplied username.

Parameters:	username – The username of the profile to retrieve.

username¶: Return the username associated with the User.

message(username, message_text)[source]¶

Message an okcupid user. If an existing conversation between the logged in user and the target user can be found, reply to that thread instead of starting a new one.

Parameters:	username (str) – The username of the user to which the message should be sent. message_text (str) – The body of the message.

search(**kwargs)[source]¶

Call SearchFetchable() to get a Fetchable object that will lazily perform okcupid searches to provide Profile objects matching the search criteria.

Defaults for gender, gentation, location and radius will be provided if none are given.

Parameters:	kwargs – See the `SearchFetchable()` docstring for details about what parameters are available.

delete_threads(thread_ids_or_threads)[source]¶

Call delete_threads().

Parameters:	thread_ids_or_threads – A list whose members are either `MessageThread` instances or okc_ids of message threads.

get_user_question(question, fast=False, bust_questions_cache=False)[source]¶

Get a UserQuestion corresponding to the given Question.

HUGE CAVEATS: If the logged in user has not answered the relevant question, it will automatically be answered with whatever the first answer to the question is.

For the sake of reducing the number of requests made when this function is called repeatedly this function does not bust the cache of this User‘s okcupyd.profile.Profile.questions attribute. That means that a question that HAS been answered could still be answered by this function if this User‘s questions was populated previously (This population happens automatically – See Fetchable for details about when and how this happens).

Parameters:

question (BaseQuestion) – The question for which a UserQuestion should be retrieved.
fast (bool) – Don’t try to look through the users existing questions to see if arbitrarily answering the question can be avoided.
bust_questions_cache (bool) – clear the questions attribute of this users Profile before looking for an existing answer. Be aware that even this does not eliminate all race conditions.

get_question_answer_id(question, fast=False, bust_questions_cache=False)[source]¶

Get the index of the answer that was given to question

See the documentation for get_user_question() for important caveats about the use of this function.

Parameters:

question (BaseQuestion) – The question whose answer_id should be retrieved.
fast (bool) – Don’t try to look through the users existing questions to see if arbitrarily answering the question can be avoided.
bust_questions_cache (bool) –

param bust_questions_cache:

clear the

questions attribute of this users Profile before looking for an existing answer. Be aware that even this does not eliminate all race conditions.

quickmatch()[source]¶: Return a Profile obtained by visiting the quickmatch page.

copy(profile_or_user)[source]¶

Create a Copy instance with the provided object as the source and this User as the destination.

Parameters:	profile_or_user – A `User` or `Profile` object.

`Profile`¶

class okcupyd.profile.Profile(session, username, **kwargs)[source]¶

Represent the profile of an okcupid user.

Many of the attributes on this object are cached_property instances which lazily load their values, and cache them once they have been accessed. This makes it so that this object avoids making unnecessary HTTP requests to retrieve the same piece of information twice.

Because of this caching behavior, care must be taken to invalidate cached attributes on the object if an up to date view of the profile is needed. It is recommended that you call refresh() to accomplish this, but it is also possible to use bust_self() to bust individual properties if necessary.

username = None¶: The username of the user to whom this profile belongs.

questions = None¶: A Fetchable of Question instances, each corresponding to a question that has been answered by the user to whom this profile belongs. The fetchable consists of UserQuestion instead when the profile belongs to the logged in user.

details = None¶: A Details instance belonging to the same user that this profile belongs to.

refresh(reload=False)[source]¶

Parameters:	reload – Make the request to return a new profile tree. This will result in the caching of the profile_tree attribute. The new profile_tree will be returned.

is_logged_in_user¶

Returns:	True if this profile and the session it was created with belong to the same user and False otherwise.

profile_tree¶

Returns:	a `lxml.etree` created from the html of the profile page of the account associated with the username that this profile was insantiated with.

photo_infos¶

Returns:	list of `Info` instances for each photo displayed on okcupid.

looking_for¶

Returns:	A `LookingFor` instance associated with this profile.

rating¶

Deprecated. Use liked() instead.

Returns:	the rating that the logged in user has given this user or 0 if no rating has been given.

liked¶

Returns:	Whether or not the logged in user liked this profile

contacted¶

Retuns:	A boolean indicating whether the logged in user has contacted the owner of this profile.

responds¶

Returns:	The frequency with which the user associated with this profile responds to messages.

id¶

Returns:	The id that okcupid.com associates with this profile.

essays¶

Returns:	A `Essays` instance that is associated with this profile.

age¶

Returns:	The age of the user associated with this profile.

match_percentage¶

Returns:	The match percentage of the logged in user and the user associated with this object.

enemy_percentage¶

Returns:	The enemy percentage of the logged in user and the user associated with this object.

location¶

Returns:	The location of the user associated with this profile.

gender¶: The gender of the user associated with this profile.

orientation¶: The sexual orientation of the user associated with this profile.

message¶

Message the user associated with this profile.

Parameters:	message – The message to send to this user. thread_id – The id of the thread to respond to, if any.

attractiveness¶

Returns:	The average attractiveness rating given to this profile by the okcupid.com community.

toggle_like()[source]¶: Toggle whether or not the logged in user likes this profile.

like()[source]¶: Like this profile.

unlike()[source]¶: Unlike this profile.

rate(rating)[source]¶

Rate this profile as the user that was logged in with the session that this object was instantiated with.

Parameters:	rating – The rating to give this user.

find_question(question_id, question_fetchable=None)[source]¶

Parameters:	question_id – The id of the question to search for question_fetchable – The question fetchable to iterate through if none is provided self.questions will be used.

question_fetchable(**kwargs)[source]¶

Returns:	A `Fetchable` instance that contains objects representing the answers that the user associated with this profile has given to okcupid.com match questions.

authcode_get(path, **kwargs)[source]¶: Perform an HTTP GET to okcupid.com using this profiles session where the authcode is automatically added as a query parameter.

authcode_post(path, **kwargs)[source]¶: Perform an HTTP POST to okcupid.com using this profiles session where the authcode is automatically added as a form item.

`LookingFor`¶

class okcupyd.looking_for.LookingFor(profile)[source]¶

Represent the looking for attributes belonging to an okcupid.com profile.

gentation¶: The sex/orientation that the user is looking for.

ages¶: The age range that the user is interested in.

single¶: Whether or not the user is only interested in people that are single.

near_me¶: Whether the user is only interested in people that are close to them.

kinds¶: The kinds of relationship tha the user is looking for.

update(ages=None, single=None, near_me=None, kinds=None, gentation=None)[source]¶

Update the looking for attributes of the logged in user.

Parameters:

ages (tuple) – The ages that the logged in user is interested in.
single (bool) – Whether or not the user is only interested in people that are single.
near_me (bool) – Whether or not the user is only interested in people that are near them.
kinds (list) – What kinds of relationships the user should be updated to be interested in.
gentation (str) – The sex/orientation of people the user is interested in.

class Ages(min, max)¶

max¶: Alias for field number 1

min¶: Alias for field number 0

`Details`¶

class okcupyd.details.Details(profile)[source]¶

Represent the details belonging to an okcupid.com profile.

classmethod name_detail_pairs()[source]¶

refresh()[source]¶

id_to_display_name_value¶

as_dict¶

convert_and_update(data)[source]¶

update(data)[source]¶

bodytype¶: The bodytype detail of an okcupid.com user’s profile.

orientation¶: The orientation detail of an okcupid.com user’s profile.

smokes¶: The smoking detail of an okcupid.com user’s profile.

drugs¶: The drugs detail of an okcupid.com user’s profile.

drinks¶: The drinking detail of an okcupid.com user’s profile.

job¶: The job detail of an okcupid.com user’s profile.

status¶: The status detail of an okcupid.com user’s profile.

monogamy¶: The monogamous detail of an okcupid.com user’s profile.

children¶: The children detail of an okcupid.com user’s profile.

education¶: The education detail of an okcupid.com user’s profile.

pets¶: The pets detail of an okcupid.com user’s profile.

diet¶: The diet detail of an okcupid.com user’s profile.

religion¶: The religion detail of an okcupid.com user’s profile.

sign¶: The sign detail of an okcupid.com user’s profile.

height¶: The height detail of an okcupid.com user’s profile.

ethnicities[source]¶: The ethnicities detail of an okcupid.com user’s profile.

income[source]¶: The income detail of an okcupid.com user’s profile.

languages[source]¶: The languages detail of an okcupid.com user’s profile.

`Essays`¶

class okcupyd.essay.Essays(profile)[source]¶

Interface to reading and writing essays.

self_summary¶: The contents of the essay labeled ‘Self Summary’. Write to this attribute to change its value for the logged in user.

my_life¶: The contents of the essay labeled ‘What I’m doing with my life’. Write to this attribute to change its value for the logged in user.

good_at¶: The contents of the essay labeled ‘I’m really good at’. Write to this attribute to change its value for the logged in user.

people_first_notice¶: The contents of the essay labeled ‘The first thing people notice about me’. Write to this attribute to change its value for the logged in user.

favorites¶: The contents of the essay labeled ‘Favorite books, movies, shows, music, and food’. Write to this attribute to change its value for the logged in user.

six_things¶: The contents of the essay labeled ‘Six things I could never live without’. Write to this attribute to change its value for the logged in user.

think_about¶: The contents of the essay labeled ‘I spend a lot of time thinking about’. Write to this attribute to change its value for the logged in user.

friday_night¶: The contents of the essay labeled ‘On a typical friday night I am’. Write to this attribute to change its value for the logged in user.

private_admission¶: The contents of the essay labeled ‘The most private thing I’m willing to admit’. Write to this attribute to change its value for the logged in user.

message_me_if¶: The contents of the essay labeled ‘You should message me if’. Write to this attribute to change its value for the logged in user.

essay_names = ['self_summary', 'my_life', 'good_at', 'people_first_notice', 'favorites', 'six_things', 'think_about', 'friday_night', 'private_admission', 'message_me_if']¶: A list of the attribute names that are used to store the text of of essays on instances of this class.

`PhotoUploader`¶

class okcupyd.photo.PhotoUploader(session=None, user_id=None, authcode=None)[source]¶

Upload photos to okcupid.com.

upload_and_confirm(incoming, **kwargs)[source]¶

Upload the file to okcupid and confirm, among other things, its thumbnail position.

Parameters:

incoming – A filepath string, Info object or a file like object to upload to okcupid.com. If an info object is provided, its thumbnail positioning will be used by default.
caption – The caption to add to the photo.
thumb_nail_left – For thumb nail positioning.
thumb_nail_top – For thumb nail positioning.
thumb_nail_right – For thumb nail positioning.
thumb_nail_bottom – For thumb nail positioning.

delete(photo_id, album_id=0)[source]¶

Delete a photo from the logged in users account.

Parameters:	photo_id – The okcupid id of the photo to delete. album_id – The album from which to delete the photo.

`Info`¶

class okcupyd.photo.Info(photo_id, tnl, tnt, tnr, tnb)[source]¶

Represent a photo that appears on a okcupid.com user’s profile.

thumb_nail_left = None¶: The horizontal position of the left side of this photo’s thumbnail.

thumb_nail_top = None¶: The vertical position of the top side of this photo’s thumbnail.

thumb_nail_right = None¶: The horizontal position of the right side of this photo’s thumbnail.

thumb_nail_bottom = None¶: The vertical position of the bottom side of this photo’s thumbnail.

jpg_uri¶

Returns:	A uri from which this photo can be downloaded in jpg format.

`MessageThread`¶

class okcupyd.messaging.MessageThread(session, thread_element)[source]¶

Represent a message thread between two users.

classmethod delete_threads(session, thread_ids_or_threads, authcode=None)[source]¶

Parameters:	session – A logged in `Session`. thread_ids_or_threads – A list whose members are either `MessageThread` instances or okc_ids of message threads. authcode – Authcode to use for this request. If none is provided A request to the logged in user’s messages page will be made to retrieve one.

messages = None¶: A Fetchable of Message objects.

id¶

Returns:	The id assigned to this message by okcupid.com.

correspondent_id¶

Returns:	The id assigned to the correspondent of this message.

correspondent¶

Returns:	The username of the user with whom the logged in user is conversing in this `MessageThread`.

read¶

Returns:	Whether or not the user has read all the messages in this `MessageThread`.

initiator¶

Returns:	A `Profile` instance belonging to the initiator of this `MessageThread`.

respondent¶

Returns:	A `Profile` instance belonging to the respondent of this `MessageThread`.

correspondent_profile¶

Returns:	The `Profile` of the user with whom the logged in user is conversing in this `MessageThread`.

user_profile¶

Returns:	A `Profile` belonging to the logged in user.

got_response¶

Returns:	Whether or not the `MessageThread`. has received a response.

delete()[source]¶: Delete this thread for the logged in user.

`Message`¶

class okcupyd.messaging.Message(message_element, message_thread)[source]¶

Represent a message sent on okcupid.com

id¶

Returns:	The id assigned to this message by okcupid.com.

sender¶

Returns:	A `Profile` instance belonging to the sender of this message.

recipient¶

Returns:	A `Profile` instance belonging to the recipient of this message.

content¶

Returns:	The text body of the message.

`Questions`¶

class okcupyd.question.Questions(session, importances=('not_important', 'little_important', 'somewhat_important', 'very_important', 'mandatory'), user_id=None)[source]¶

Interface to accessing and answering questions belonging to the logged in user.

mandatory¶: A Fetchable of UserQuestion instances that correspond to questions that have been answered by the logged in user and assigned the ‘mandatory’ importance.

very_important¶: A Fetchable of UserQuestion instances that correspond to questions that have been answered by the logged in user and assigned the ‘very_important’ importance.

somewhat_important¶: A Fetchable of UserQuestion instances that correspond to questions that have been answered by the logged in user and assigned the ‘somewhat_important’ importance.

little_important¶: A Fetchable of UserQuestion instances that correspond to questions that have been answered by the logged in user and assigned the ‘little_important’ importance.

not_important¶: A Fetchable of UserQuestion instances that correspond to questions that have been answered by the logged in user and assigned the ‘not_important’ importance.

importance_name_to_number = {'mandatory': 0, 'not_important': 5, 'very_important': 1, 'little_important': 4, 'somewhat_important': 3}¶: Human readable importance name to integer used to represent them on okcupid.com

respond_from_user_question(user_question, importance)[source]¶

Respond to a question in exactly the way that is described by the given user_question.

Parameters:	user_question (`UserQuestion`) – The user question to respond with. importance (int see `importance_name_to_number`) – The importance that should be used in responding to the question.

respond_from_question(question, user_question, importance)[source]¶

Copy the answer given in question to the logged in user’s profile.

Parameters:	question – A `Question` instance to copy. user_question – An instance of `UserQuestion` that corresponds to the same question as question. This is needed to retrieve the answer id from the question text answer on question. importance – The importance to assign to the response to the answered question.

respond(question_id, user_response_ids, match_response_ids, importance, note='', is_public=1, is_new=1)[source]¶

Respond to an okcupid.com question.

Parameters:

question_id – The okcupid id used to identify this question.
user_response_ids – The answer id(s) to provide to this question.
match_response_ids – The answer id(s) that the user considers acceptable.
importance – The importance to attribute to this question. See importance_name_to_number for details.
note – The explanation note to add to this question.
is_public – Whether or not the question answer should be made public.

clear()[source]¶: USE WITH CAUTION. Delete the answer to every question that the logged in user has responded to.

`Question`¶

class okcupyd.question.Question(question_element)[source]¶

Represent a question answered by a user other than the logged in user.

Note: Because of the way that okcupid presents question data it is actually not very easy to get the index of the answer to a question that belongs to a user other than the logged in user. It is possible to retrieve this value (see okcupyd.user.User.get_question_answer_id() and get_answer_id_for_question()), but it can take quite a few requests to do so. For this reason, the answer_id is NOT included as an attribute on this object, despite its inclusion in UserQuestion.

their_answer¶: The answer that the user whose Profile this question was retrieved from provided to this Question.

my_answer¶: The answer that the user whose Session was used to create this Question provided.

their_answer_matches¶

Returns:	whether or not the answer provided by the user answering the question is acceptable to the logged in user.
Return type:	rbool

my_answer_matches¶

Returns:	bool indicating whether or not the answer provided by the logged in user is acceptable to the user answering the question.

their_note¶

Returns:	The note the answering user provided as explanation for their answer to this question.

my_note¶

Returns:	The note the logged in user provided as an explanation for their answer to this question.

`UserQuestion`¶

class okcupyd.question.UserQuestion(question_element)[source]¶

Represent a question answered by the logged in user.

get_answer_id_for_question(question)[source]¶

Get the answer_id corresponding to the answer given for question by looking at this UserQuestion‘s answer_options. The given Question instance must have the same id as this UserQuestion.

That this method exists is admittedly somewhat weird. Unfortunately, it seems to be the only way to retrieve this information.

answer_options¶

Returns:	A list of `AnswerOption` instances representing the available answers to this question.

explanation¶

Returns:	The explanation written by the logged in user for this question (if any).

answer¶

Returns:	A `AnswerOption` instance corresponding to the answer the user gave to this question.

`AnswerOption`¶

class okcupyd.question.AnswerOption(option_element)[source]¶

is_users¶

Returns:	Whether or not this was the answer selected by the logged in user.

is_match¶

Returns:	Whether or not this was the answer is acceptable to the logged in user.

text¶

Returns:	The text of this answer.

id¶

Returns:	The integer index associated with this answer.

`SearchFetchable()`¶

okcupyd.json_search.SearchFetchable(session=None, **kwargs)[source]¶

Search okcupid.com with the given parameters. Parameters are registered to this function through register_filter_builder() of search_filters.

Returns:

A Fetchable of Profile instances.

Parameters:

session (Session) – A logged in session.
gentation (list) – A list of the allowable gentations of returned search results. expected values: ‘women who like men’, ‘’, ‘men who like women’, ‘gay men only’, ‘bi men and women’, ‘straight girls only’, ‘gay guys only’, ‘girls who like guys’, ‘gay girls only’, ‘women’, ‘both who like bi girls’, ‘guys who like girls’, ‘both who like bi women’, ‘straight women only’, ‘bi guys only’, ‘women who like women’, ‘everybody’, ‘bi girls only’, ‘guys and girls who like bi girls’, ‘bi men only’, ‘men and women who like bi women’, ‘gay women only’, ‘bi women only’, ‘both who like bi men’, ‘men who like men’, ‘bi guys and girls’, ‘men and women who like bi men’, ‘guys who like guys’, ‘straight men only’, ‘guys and girls who like bi guys’, ‘girls who like girls’, ‘both who like bi guys’, ‘straight guys only’
location – A query that will be used to look up a locid for the search, location_cache must also be passed in in order for this parameter to work. User automatically passes the location_cache in.
location_cache – A LocationQueryCache instance.
locid (int) –
maximum_age (int) – Filter profiles with ages below the provided value.
minimum_age (int) – Filter profiles with ages above the provided value.
order_by –
radius ((<class 'int'>, <class 'NoneType'>)) – The maximum distance (in miles) from the specified location of returned search results.

`_AttractivenessFinder`¶

class okcupyd.attractiveness_finder._AttractivenessFinder(session=None)[source]¶

Find the attractiveness of okcupid.com users.

This class is typically wrapped in several different attractiveness finder decorators that allow for cacheing of results and rounding.

find_attractiveness(username, accuracy=1000, _lower=0, _higher=10000)[source]¶

Parameters:	username – The username to lookup attractiveness for. accuracy – The accuracy required to return a result. _lower – The lower bound of the search. _higher – The upper bound of the search.

`Copy`¶

class okcupyd.profile_copy.Copy(source_profile_or_user, dest_user)[source]¶

Copy photos, essays and other attributes from one profile to another.

__init__(source_profile_or_user, dest_user)[source]¶

Parameters:	source_profile_or_user – A `User` or `Profile` object from which to copy attributes. `questions()` will not will not preserve the importance of copied questions if a `Profile` instance is provided. dest_user – A `User` to which data will be copied

questions()[source]¶: Copy questions to the destination user. When this class was initialized with a Profile, this will delete any existing questions answers on the destination account.

photos()[source]¶: Copy photos to the destination user.

essays()[source]¶: Copy essays from the source profile to the destination profile.

looking_for()[source]¶: Copy looking for attributes from the source profile to the destination profile.

details()[source]¶: Copy details from the source profile to the destination profile.

all()[source]¶: Invoke all of questions(), details(), essays(), photos(), looking_for()

`Statistics`¶

class okcupyd.statistics.Statistics(user, message_threads=None, filters=(), attractiveness_finder=None)[source]¶

`add_command_line_options()`¶

okcupyd.util.misc.add_command_line_options(add_argument, use_short_options=True)[source]¶

Parameters:	add_argument – The add_argument method of an ArgParser. use_short_options – Whether or not to add short options.

`handle_command_line_options()`¶

okcupyd.util.misc.handle_command_line_options(args)[source]¶

Parameters:	args – The args returned from an ArgParser