Warnings now do their best to provide an appropriate stacklevel,

  improving the usefulness of the message. [bug=1978744]

5 files changed, 25 insertions, 14 deletions

diff --git a/CHANGELOG b/CHANGELOG
index 066c8c7..39cf884 100644
--- a/CHANGELOG
+++ b/CHANGELOG
@@ -6,8 +6,9 @@ Bazaar repository, the final revision to support Python 2 was 605.
 
 = Unreleased
 
-* Fixed a test failure when cchardet is not installed but
-  charset_normalizer is. [bug=1973072]
+* Fixed test failures caused by nondeterministic behavior of
+  UnicodeDammit's character detection, depending on the platform setup.
+  [bug=1973072]
 
 * Fixed another crash when overriding multi_valued_attributes and using the
   html5lib parser. [bug=1948488]
@@ -18,6 +19,9 @@ Bazaar repository, the final revision to support Python 2 was 605.
 * Tag.interesting_string_types is now propagated when a tag is
   copied. [bug=1990400]
 
+* Warnings now do their best to provide an appropriate stacklevel,
+  improving the usefulness of the error message. [bug=1978744]
+
 * Passing a Tag's .contents into PageElement.extend() now works the
   same way as passing the Tag itself.
 
diff --git a/bs4/__init__.py b/bs4/__init__.py
index b3c9feb..887ed19 100644
--- a/bs4/__init__.py
+++ b/bs4/__init__.py
@@ -405,7 +405,8 @@ class BeautifulSoup(Tag):
                     'The input looks more like a URL than markup. You may want to use'
                     ' an HTTP client like requests to get the document behind'
                     ' the URL, and feed that document to Beautiful Soup.',
-                    MarkupResemblesLocatorWarning
+                    MarkupResemblesLocatorWarning,
+                    stacklevel=3
                 )
                 return True
         return False
@@ -436,7 +437,7 @@ class BeautifulSoup(Tag):
                 'The input looks more like a filename than markup. You may'
                 ' want to open this file and pass the filehandle into'
                 ' Beautiful Soup.',
-                MarkupResemblesLocatorWarning
+                MarkupResemblesLocatorWarning, stacklevel=3
             )
             return True
         return False
@@ -789,7 +790,7 @@ class BeautifulStoneSoup(BeautifulSoup):
         warnings.warn(
             'The BeautifulStoneSoup class is deprecated. Instead of using '
             'it, pass features="xml" into the BeautifulSoup constructor.',
-            DeprecationWarning
+            DeprecationWarning, stacklevel=2
         )
         super(BeautifulStoneSoup, self).__init__(*args, **kwargs)
 
diff --git a/bs4/builder/_html5lib.py b/bs4/builder/_html5lib.py
index 12dee07..dac2173 100644
--- a/bs4/builder/_html5lib.py
+++ b/bs4/builder/_html5lib.py
@@ -70,7 +70,10 @@ class HTML5TreeBuilder(HTMLTreeBuilder):
         # ATM because the html5lib TreeBuilder doesn't use
         # UnicodeDammit.
         if exclude_encodings:
-            warnings.warn("You provided a value for exclude_encoding, but the html5lib tree builder doesn't support exclude_encoding.")
+            warnings.warn(
+                "You provided a value for exclude_encoding, but the html5lib tree builder doesn't support exclude_encoding.",
+                stacklevel=3
+            )
 
         # html5lib only parses HTML, so if it's given XML that's worth
         # noting.
@@ -81,7 +84,10 @@ class HTML5TreeBuilder(HTMLTreeBuilder):
     # These methods are defined by Beautiful Soup.
     def feed(self, markup):
         if self.soup.parse_only is not None:
-            warnings.warn("You provided a value for parse_only, but the html5lib tree builder doesn't support parse_only. The entire document will be parsed.")
+            warnings.warn(
+                "You provided a value for parse_only, but the html5lib tree builder doesn't support parse_only. The entire document will be parsed.",
+                stacklevel=4
+            )
         parser = html5lib.HTMLParser(tree=self.create_treebuilder)
         self.underlying_builder.parser = parser
         extra_kwargs = dict()
diff --git a/bs4/builder/_htmlparser.py b/bs4/builder/_htmlparser.py
index fae4d0f..52cebe6 100644
--- a/bs4/builder/_htmlparser.py
+++ b/bs4/builder/_htmlparser.py
@@ -95,12 +95,12 @@ class BeautifulSoupHTMLParser(HTMLParser, DetectsXMLParsedAsHTML):
         """In Python 3, HTMLParser subclasses must implement error(), although
         this requirement doesn't appear to be documented.
 
-        In Python 2, HTMLParser implements error() by raising an exception,
-        which we don't want to do.
-
         In any event, this method is called only on very strange
         markup and our best strategy is to pretend it didn't happen
         and keep going.
+
+        NOTE: this was deprecated in Python 3.4, and removed in 3.5.
+        Since Beautiful Soup support starts at 3.6, this can be removed.
         """
         warnings.warn(msg)
         
diff --git a/bs4/element.py b/bs4/element.py
index 7f25f27..9b54d43 100644
--- a/bs4/element.py
+++ b/bs4/element.py
@@ -786,7 +786,7 @@ class PageElement(object):
             string = kwargs.pop('text')
             warnings.warn(
                 "The 'text' argument to find()-type methods is deprecated. Use 'string' instead.",
-                DeprecationWarning
+                DeprecationWarning, stacklevel=3
             )
 
         if isinstance(name, SoupStrainer):
@@ -1562,7 +1562,7 @@ class Tag(PageElement):
                 '.%(name)sTag is deprecated, use .find("%(name)s") instead. If you really were looking for a tag called %(name)sTag, use .find("%(name)sTag")' % dict(
                     name=tag_name
                 ),
-                DeprecationWarning
+                DeprecationWarning, stacklevel=2
             )
             return self.find(tag_name)
         # We special case contents to avoid recursion.
@@ -1997,7 +1997,7 @@ class Tag(PageElement):
         """
         warnings.warn(
             'has_key is deprecated. Use has_attr(key) instead.',
-            DeprecationWarning
+            DeprecationWarning, stacklevel=2
         )
         return self.has_attr(key)
 
@@ -2028,7 +2028,7 @@ class SoupStrainer(object):
             string = kwargs.pop('text')
             warnings.warn(
                 "The 'text' argument to the SoupStrainer constructor is deprecated. Use 'string' instead.",
-                DeprecationWarning
+                DeprecationWarning, stacklevel=2
             )
 
         self.name = self._normalize_search_value(name)