README.rst 5.2 KB

  1. =========
  2. webfinger
  3. =========
  4. A simple Python client implementation of `WebFinger RFC 7033 <>`_.
  5. WebFinger is a discovery protocol that allows you to find information about people or things in a standardized way. See the `spec <>`_ or ` <>`_ for more information.
  6. ::
  7. >>> from webfinger import finger
  8. >>> wf = finger('')
  9. >>> wf.subject
  11. >>> wf.avatar
  13. >>> wf.profile
  15. >>>'')
  16. Eric Mill
  17. Installation
  18. ============
  19. Available on `PyPI as webfinger <>`_.
  20. pip install webfinger
  21. finger
  22. ======
  23. finger(resource, rel=None)
  24. *finger* is a convenience method for 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.
  25. WebFingerClient supports additional options, so check that out if *finger* does not meet your needs.
  26. WebFinger Client
  27. ================
  28. WebFingerClient(timeout=None, official=False)
  29. Instantiates a client object. The optional *timeout* parameter specifies the HTTP request timeout. The optional *official* parameter is a boolean that determines if the client will use `unofficial endpoints`_.
  30. finger(resource, host=None, rel=None, raw=False)
  31. The client *finger* method prepares and executes the WebFinger request. *resource* and *rel* are the same as the parameters on the standalone *finger* method. *host* should only be specified if you want to connect to a host other than the host in the resource parameter. Otherwise, this method extracts the host from the *resource* parameter. *raw* is a boolean that determines if the method returns a WebFingerResponse object or the raw JRD response as a dict.
  32. If the *host* parameter is passed to this method, unofficial endpoints are ignored. You're asking for a specific host so who am I to disagree?
  33. WebFinger Response
  34. ==================
  35. The WebFinger response object provides handy properties for easy access and the raw JRD response. Read the `spec for specifics of the JRD response <>`_.
  36. Properties
  37. ----------
  38. subject
  39. The URI of the thing that the response JRD describes.
  40. aliases
  41. A list of additional URIs that identify the subject.
  42. properties
  43. A dict of URIs and values that provides information about the subject.
  44. links
  45. A list of dicts that define external resources for the subject.
  46. jrd
  47. A dict of the raw JRD response.
  48. Methods
  49. -------
  50. rel(relation, attr='href')
  51. 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*.
  52. ::
  53. >>> wf.rel('')
  55. 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.
  56. ::
  57. >>> rel = ''
  58. >>> [l.get('href') for l in rel.links if l.get('rel') == rel]
  59. If *attr* is None, the full dict for the link will be returned.
  60. Relation Properties
  61. -------------------
  62. The following common link relation types are supported as properties of the response object:
  63. * activity_streams:
  64. * avatar:
  65. * hcard:
  66. * open_id:
  67. * opensocial:
  68. * portable_contacts:
  69. * profile:
  70. * webfist:
  71. * xfn:
  72. Example::
  73. >>> wf.avatar
  75. .. _unofficial endpoints:
  76. Unofficial Endpoints
  77. ====================
  78. 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 the unofficial endpoints for and resource domains. This behavior can be disabled by passing *True* to the *official* parameter::
  79. >>> wf = finger('', official=True)
  80. Dependencies
  81. ============
  82. * `requests <>`_
  83. License
  84. =======
  85. python-webfinger is distributed under the `BSD license <>`_.
  86. See LICENSE for the full terms.