From d34818461115454385dbf275dd0ad394c7f6cab2 Mon Sep 17 00:00:00 2001 From: Jeremy Carbaugh Date: Sat, 2 Nov 2013 02:49:34 -0400 Subject: [PATCH] Update README for 1.0 release --- README.rst | 90 ++++++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 78 insertions(+), 12 deletions(-) diff --git a/README.rst b/README.rst index c650791..d7aae67 100644 --- a/README.rst +++ b/README.rst @@ -2,18 +2,72 @@ webfinger ========= +A simple Python client implementation of `WebFinger RFC 7033 `_. + +WebFinger is a discovery protocol that allows you to find information about people or things in a standardized way. See the `spec `_ or `webfinger.net `_ for more information. + + Usage -===== +----- Example:: - from webfinger import finger + >>> from webfinger import finger + >>> wf = finger('acct:eric@konklone.com') + >>> wf.subject + acct:eric@konklone.com + >>> wf.avatar + https://secure.gravatar.com/avatar/ac3399caecce27cb19d381f61124539e.jpg?s=400 + >>> wf.profile + https://konklone.com + >>> wf.properties.get('http://schema.org/name') + Eric Mill - wf = finger('user@host.com') - print wf.profile - print wf.hcard -The following relation types are supported: +WebFinger Response +------------------ + +The WebFinger response object provides handy properties for easy access and the raw JRD response. Read the `spec for specifics of the JRD response `_. + + +---------- +Properties +---------- + +subject + The URI of the thing that the response JRD describes. + +aliases + A list of additional URIs that identify the subject. + +properties + A dict of URIs and values that provides information about the subject. + +links + A list of dicts that define external resources for the subject. + +jrd + A dict of the raw JRD response. + + +------- +Methods +------- + +rel(relation, attr='href') + A convenience method that provides basic access to links. The *relation* parameter is a URI for the desired link. The *attr* parameter is the key of the returned value of the link that matches *relation*. Returns a string if *relation* and *attr* exist, otherwise *None*. + +Example:: + + >>> wf.rel('http://webfinger.net/rel/avatar') + https://secure.gravatar.com/avatar/ac3399caecce27cb19d381f61124539e.jpg?s=400 + + +------------------- +Relation Properties +------------------- + +The following common link relation types are supported as properties of the response object: * activity_streams: http://activitystrea.ms/spec/1.0 * avatar: http://webfinger.net/rel/avatar @@ -22,20 +76,32 @@ The following relation types are supported: * opensocial: http://ns.opensocial.org/2008/opensocial/activitystreams * portable_contacts: http://portablecontacts.net/spec/1.0 * profile: http://webfinger.net/rel/profile-page +* webfist: http://webfist.org/spec/rel * xfn: http://gmpg.org/xfn/11 -Other relation types can be accessed directly from the XRD document.:: +Example:: + + >>> wf.avatar + https://secure.gravatar.com/avatar/ac3399caecce27cb19d381f61124539e.jpg?s=400 + + +Unofficial Endpoints +-------------------- + +While Facebook and Twitter do not officially support WebFinger, the `webfinger-unofficial project `_ provides a proxy for basic subject information. By default, python-webfinger will attempt to use unoffical the endpoints for facebook.com and twitter.com resource domains. This behavior can be disabled by passing *True* to the *official* parameter:: + + >>> wf = finger('acct:konklone@twitter.com', official=True) - print wf.find_link('http://example.com/example/spec', attr='href') Dependencies -============ +------------ + +* `requests `_ -* `python-rd `_ License -======= +------- python-webfinger is distributed under the `BSD license `_. -See LICENSE for the full terms of the BSD license. +See LICENSE for the full terms.