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