kopia lustrzana https://github.com/jcarbaugh/python-webfinger
Update README with documentation for client object
rodzic
52748e92b4
commit
5ef1ee3afa
49
README.rst
49
README.rst
|
@ -6,11 +6,7 @@ A simple Python client implementation of `WebFinger RFC 7033 <http://tools.ietf.
|
||||||
|
|
||||||
WebFinger is a discovery protocol that allows you to find information about people or things in a standardized way. See the `spec <http://tools.ietf.org/html/rfc7033>`_ or `webfinger.net <http://webfinger.net>`_ for more information.
|
WebFinger is a discovery protocol that allows you to find information about people or things in a standardized way. See the `spec <http://tools.ietf.org/html/rfc7033>`_ or `webfinger.net <http://webfinger.net>`_ for more information.
|
||||||
|
|
||||||
|
::
|
||||||
Usage
|
|
||||||
-----
|
|
||||||
|
|
||||||
Example::
|
|
||||||
|
|
||||||
>>> from webfinger import finger
|
>>> from webfinger import finger
|
||||||
>>> wf = finger('acct:eric@konklone.com')
|
>>> wf = finger('acct:eric@konklone.com')
|
||||||
|
@ -24,13 +20,32 @@ Example::
|
||||||
Eric Mill
|
Eric Mill
|
||||||
|
|
||||||
|
|
||||||
|
finger
|
||||||
|
======
|
||||||
|
|
||||||
|
finger(resource, rel=None, timeout=None, official=False)
|
||||||
|
The *finger* method provides a simple way of instantiating a WebFingerClient object and making the request. The *resource* parameter is a URI of the resource about which you are querying. The optional *rel* parameter can be either a string or a list of strings that will limit the response to the specific relations. WebFinger servers are **not** required to obey the *rel* parameter, so you should handle the response accordingly. The optional *timeout* parameter can set a specific HTTP request timeout. The *official* parameter is a boolean that determines if the client will use `unofficial endpoints`_.
|
||||||
|
|
||||||
|
|
||||||
|
WebFinger Client
|
||||||
|
================
|
||||||
|
|
||||||
|
WebFingerClient(timeout=None, official=False)
|
||||||
|
Instantiates a client object. *timeout* and *official* are the same as the parameters on the standalone *finger* method.
|
||||||
|
|
||||||
|
finger(resource, rel=None)
|
||||||
|
The client *finger* method prepares and executes the WebFinger request. *resource* and *rel* are the same as the parameters on the standalone *finger* method. This method extracts the host from the *resource* parameter and invokes the *jrd* method.
|
||||||
|
|
||||||
|
jrd(host, resource, rel, raw=False)
|
||||||
|
The *jrd* method is the core of the client object. It executes the HTTP request and creates the response object. *host* is a string of the host against which the request will be executed. *resource* and *rel* are the same as the parameters on the standalone *finger* method. *raw* is a boolean that determines if the method returns a WebFingerResponse object or the raw JRD response as a dict.
|
||||||
|
|
||||||
|
|
||||||
WebFinger Response
|
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 <http://tools.ietf.org/html/rfc7033#section-4.4>`_.
|
The WebFinger response object provides handy properties for easy access and the raw JRD response. Read the `spec for specifics of the JRD response <http://tools.ietf.org/html/rfc7033#section-4.4>`_.
|
||||||
|
|
||||||
|
|
||||||
----------
|
|
||||||
Properties
|
Properties
|
||||||
----------
|
----------
|
||||||
|
|
||||||
|
@ -50,20 +65,26 @@ jrd
|
||||||
A dict of the raw JRD response.
|
A dict of the raw JRD response.
|
||||||
|
|
||||||
|
|
||||||
-------
|
|
||||||
Methods
|
Methods
|
||||||
-------
|
-------
|
||||||
|
|
||||||
rel(relation, attr='href')
|
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*.
|
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')
|
>>> wf.rel('http://webfinger.net/rel/avatar')
|
||||||
https://secure.gravatar.com/avatar/ac3399caecce27cb19d381f61124539e.jpg?s=400
|
https://secure.gravatar.com/avatar/ac3399caecce27cb19d381f61124539e.jpg?s=400
|
||||||
|
|
||||||
|
The response JRD may have multiple entries with the same relation URI. The *rel* method will select the first one, since order is meant to imply priority. If you need to see all of the values, you'll have to iterate over the *links* property and pull them out yourself.
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
>>> rel = 'http://webfinger.net/rel/avatar'
|
||||||
|
>>> [l.get('href') for l in rel.links if l.get('rel') == rel]
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
-------------------
|
|
||||||
Relation Properties
|
Relation Properties
|
||||||
-------------------
|
-------------------
|
||||||
|
|
||||||
|
@ -85,8 +106,10 @@ Example::
|
||||||
https://secure.gravatar.com/avatar/ac3399caecce27cb19d381f61124539e.jpg?s=400
|
https://secure.gravatar.com/avatar/ac3399caecce27cb19d381f61124539e.jpg?s=400
|
||||||
|
|
||||||
|
|
||||||
|
.. _unofficial endpoints:
|
||||||
|
|
||||||
Unofficial Endpoints
|
Unofficial Endpoints
|
||||||
--------------------
|
====================
|
||||||
|
|
||||||
While Facebook and Twitter do not officially support WebFinger, the `webfinger-unofficial project <https://github.com/snarfed/webfinger-unofficial>`_ 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::
|
While Facebook and Twitter do not officially support WebFinger, the `webfinger-unofficial project <https://github.com/snarfed/webfinger-unofficial>`_ 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::
|
||||||
|
|
||||||
|
@ -94,13 +117,13 @@ While Facebook and Twitter do not officially support WebFinger, the `webfinger-u
|
||||||
|
|
||||||
|
|
||||||
Dependencies
|
Dependencies
|
||||||
------------
|
============
|
||||||
|
|
||||||
* `requests <https://pypi.python.org/pypi/requests>`_
|
* `requests <https://pypi.python.org/pypi/requests>`_
|
||||||
|
|
||||||
|
|
||||||
License
|
License
|
||||||
-------
|
=======
|
||||||
|
|
||||||
python-webfinger is distributed under the `BSD license <http://creativecommons.org/licenses/BSD/>`_.
|
python-webfinger is distributed under the `BSD license <http://creativecommons.org/licenses/BSD/>`_.
|
||||||
|
|
||||||
|
|
Ładowanie…
Reference in New Issue