Doc/library/robotparser.rst

   1
   2 :mod:`robotparser` ---  Parser for robots.txt
   3 =============================================
   4
   5 .. module:: robotparser
   6    :synopsis: Loads a robots.txt file and answers questions about
   7               fetchability of other URLs.
   8 .. sectionauthor:: Skip Montanaro <skip@pobox.com>
   9
  10
  11 .. index::
  12    single: WWW
  13    single: World Wide Web
  14    single: URL
  15    single: robots.txt
  16
  17 This module provides a single class, :class:`RobotFileParser`, which answers
  18 questions about whether or not a particular user agent can fetch a URL on the
  19 Web site that published the :file:`robots.txt` file.  For more details on the
  20 structure of :file:`robots.txt` files, see http://www.robotstxt.org/orig.html.
  21
  22
  23 .. class:: RobotFileParser()
  24
  25    This class provides a set of methods to read, parse and answer questions
  26    about a single :file:`robots.txt` file.
  27
  28
  29    .. method:: set_url(url)
  30
  31       Sets the URL referring to a :file:`robots.txt` file.
  32
  33
  34    .. method:: read()
  35
  36       Reads the :file:`robots.txt` URL and feeds it to the parser.
  37
  38
  39    .. method:: parse(lines)
  40
  41       Parses the lines argument.
  42
  43
  44    .. method:: can_fetch(useragent, url)
  45
  46       Returns ``True`` if the *useragent* is allowed to fetch the *url*
  47       according to the rules contained in the parsed :file:`robots.txt`
  48       file.
  49
  50
  51    .. method:: mtime()
  52
  53       Returns the time the ``robots.txt`` file was last fetched.  This is
  54       useful for long-running web spiders that need to check for new
  55       ``robots.txt`` files periodically.
  56
  57
  58    .. method:: modified()
  59
  60       Sets the time the ``robots.txt`` file was last fetched to the current
  61       time.
  62
  63 The following example demonstrates basic use of the RobotFileParser class. ::
  64
  65    >>> import robotparser
  66    >>> rp = robotparser.RobotFileParser()
  67    >>> rp.set_url("http://www.musi-cal.com/robots.txt")
  68    >>> rp.read()
  69    >>> rp.can_fetch("*", "http://www.musi-cal.com/cgi-bin/search?city=San+Francisco")
  70    False
  71    >>> rp.can_fetch("*", "http://www.musi-cal.com/")
  72    True
  73