Python tool for converting files and office documents to Markdown.
Fix typos and formatting in comments, docstrings, and markdown (#2223)
Chien Yuan Chang24c14c6ba543
diff --git a/README.md b/README.mdindex aa2f58bb..37be2d1d 100644--- a/README.md+++ b/README.md@@ -20,7 +20,7 @@ MarkItDown currently supports the conversion from:- HTML- Text-based formats (CSV, JSON, XML)- ZIP files (iterates over contents)-- Youtube URLs+- YouTube URLs- EPubs- ... and more!@@ -341,9 +341,9 @@ You can help by looking at issues or helping review PRs. Any issue or PR is welc### Security Considerations-MarkItDown performs I/O with the privileges of the current process. Like `open()` or `requests.get()`, it will access resources that the process itself can access.+MarkItDown performs I/O with the privileges of the current process. Like `open()` or `requests.get()`, it will access resources that the process itself can access.-**Sanitize your inputs:** Do not pass untrusted input directly to MarkItDown. If any part of the input may be controlled by an untrusted user or system, such as in hosted or server-side applications, it must be validated and restricted before calling MarkItDown. Depending on your environment, this may include restricting file paths, limiting URI schemes and network destinations, and blocking access to private, loopback, link-local, or metadata-service addresses.+**Sanitize your inputs:** Do not pass untrusted input directly to MarkItDown. If any part of the input may be controlled by an untrusted user or system, such as in hosted or server-side applications, it must be validated and restricted before calling MarkItDown. Depending on your environment, this may include restricting file paths, limiting URI schemes and network destinations, and blocking access to private, loopback, link-local, or metadata-service addresses.**Call only the conversion method you need:** Prefer the narrowest conversion API that fits your use case. MarkItDown's `convert()` method is intentionally permissive and can handle local files, remote URIs, and byte streams. If your application only needs to read local files, call `convert_local()` instead. If you need more control over URI fetching, call `requests.get()` yourself and pass the response object to `convert_response()`. For maximum control, open a stream to the input you want converted and call `convert_stream()`.diff --git a/packages/markitdown-mcp/README.md b/packages/markitdown-mcp/README.mdindex d7e9224b..508e7b59 100644--- a/packages/markitdown-mcp/README.md+++ b/packages/markitdown-mcp/README.md@@ -25,13 +25,13 @@ pip install markitdown-mcpTo run the MCP server, using STDIO (default), use the following command:-```bash+```bashmarkitdown-mcp```To run the MCP server, using Streamable HTTP and SSE, use the following command:-```bash+```bashmarkitdown-mcp --http --host 127.0.0.1 --port 3001```@@ -86,12 +86,12 @@ If you want to mount a directory, adjust it accordingly:"markitdown": {"command": "docker","args": [- "run",- "--rm",- "-i",- "-v",- "/home/user/data:/workdir",- "markitdown-mcp:latest"+ "run",+ "--rm",+ "-i",+ "-v",+ "/home/user/data:/workdir",+ "markitdown-mcp:latest"]}}diff --git a/packages/markitdown-sample-plugin/README.md b/packages/markitdown-sample-plugin/README.mdindex adf1d9e7..b7503134 100644--- a/packages/markitdown-sample-plugin/README.md+++ b/packages/markitdown-sample-plugin/README.md@@ -7,16 +7,16 @@This project shows how to create a sample plugin for MarkItDown. The most important parts are as follows:-Next, implement your custom DocumentConverter:+First, implement your custom DocumentConverter:```pythonfrom typing import BinaryIO, Any-from markitdown import MarkItDown, DocumentConverter, DocumentConverterResult, StreamInfo+from markitdown import MarkItDown, DocumentConverter, DocumentConverterResult, StreamInfo, PRIORITY_SPECIFIC_FILE_FORMATclass RtfConverter(DocumentConverter):def __init__(- self, priority: float = DocumentConverter.PRIORITY_SPECIFIC_FILE_FORMAT+ self, priority: float = PRIORITY_SPECIFIC_FILE_FORMAT):super().__init__(priority=priority)@@ -26,10 +26,10 @@ class RtfConverter(DocumentConverter):stream_info: StreamInfo,**kwargs: Any,) -> bool:-- # Implement logic to check if the file stream is an RTF file- # ...- raise NotImplementedError()++ # Implement logic to check if the file stream is an RTF file+ # ...+ raise NotImplementedError()def convert(@@ -39,17 +39,17 @@ class RtfConverter(DocumentConverter):**kwargs: Any,) -> DocumentConverterResult:- # Implement logic to convert the file stream to Markdown- # ...- raise NotImplementedError()+ # Implement logic to convert the file stream to Markdown+ # ...+ raise NotImplementedError()```Next, make sure your package implements and exports the following:```python-# The version of the plugin interface that this plugin uses.+# The version of the plugin interface that this plugin uses.# The only supported version is 1 for now.-__plugin_interface_version__ = 1+__plugin_interface_version__ = 1# The main entrypoint for the plugin. This is called each time MarkItDown instances are created.def register_converters(markitdown: MarkItDown, **kwargs):@@ -97,7 +97,7 @@ In Python, plugins can be enabled as follows:```pythonfrom markitdown import MarkItDown-md = MarkItDown(enable_plugins=True)+md = MarkItDown(enable_plugins=True)result = md.convert("path-to-file.rtf")print(result.text_content)```diff --git a/packages/markitdown-sample-plugin/src/markitdown_sample_plugin/_plugin.py b/packages/markitdown-sample-plugin/src/markitdown_sample_plugin/_plugin.pyindex 1ca00ccc..f47bba6a 100644--- a/packages/markitdown-sample-plugin/src/markitdown_sample_plugin/_plugin.py+++ b/packages/markitdown-sample-plugin/src/markitdown_sample_plugin/_plugin.py@@ -33,7 +33,7 @@ def register_converters(markitdown: MarkItDown, **kwargs):class RtfConverter(DocumentConverter):"""- Converts an RTF file to in the simplest possible way.+ Converts an RTF file in the simplest possible way."""def accepts(@@ -60,7 +60,7 @@ class RtfConverter(DocumentConverter):stream_info: StreamInfo,**kwargs: Any,) -> DocumentConverterResult:- # Read the file stream into an str using hte provided charset encoding, or using the system default+ # Read the file stream into a str using the provided charset encoding, or using the system defaultencoding = stream_info.charset or locale.getpreferredencoding()stream_data = file_stream.read().decode(encoding)diff --git a/packages/markitdown-sample-plugin/tests/test_sample_plugin.py b/packages/markitdown-sample-plugin/tests/test_sample_plugin.pyindex 69682474..0ffaa663 100644--- a/packages/markitdown-sample-plugin/tests/test_sample_plugin.py+++ b/packages/markitdown-sample-plugin/tests/test_sample_plugin.py@@ -13,7 +13,7 @@ RTF_TEST_STRINGS = {def test_converter() -> None:- """Tests the RTF converter dirctly."""+ """Tests the RTF converter directly."""with open(os.path.join(TEST_FILES_DIR, "test.rtf"), "rb") as file_stream:converter = RtfConverter()result = converter.convert(diff --git a/packages/markitdown/README.md b/packages/markitdown/README.mdindex bedcba18..0b6b67b1 100644--- a/packages/markitdown/README.md+++ b/packages/markitdown/README.md@@ -1,7 +1,7 @@# MarkItDown> [!TIP]-> MarkItDown is a Python package and command-line utility for converting various files to Markdown (e.g., for indexing, text analysis, etc).+> MarkItDown is a Python package and command-line utility for converting various files to Markdown (e.g., for indexing, text analysis, etc).>> For more information, and full documentation, see the project [README.md](https://github.com/microsoft/markitdown) on GitHub.@@ -13,7 +13,7 @@From PyPI:```bash-pip install markitdown[all]+pip install 'markitdown[all]'```From source:@@ -21,7 +21,7 @@ From source:```bashgit clone [email protected]:microsoft/markitdown.gitcd markitdown-pip install -e packages/markitdown[all]+pip install -e 'packages/markitdown[all]'```## Usagediff --git a/packages/markitdown/src/markitdown/__main__.py b/packages/markitdown/src/markitdown/__main__.pyindex ccb44b64..56eb89cd 100644--- a/packages/markitdown/src/markitdown/__main__.py+++ b/packages/markitdown/src/markitdown/__main__.py@@ -75,7 +75,7 @@ def main():parser.add_argument("-c","--charset",- help="Provide a hint about the file's charset (e.g, UTF-8).",+ help="Provide a hint about the file's charset (e.g., UTF-8).",)cloud_group = parser.add_mutually_exclusive_group()diff --git a/packages/markitdown/src/markitdown/_base_converter.py b/packages/markitdown/src/markitdown/_base_converter.pyindex fa2b1114..1ed84097 100644--- a/packages/markitdown/src/markitdown/_base_converter.py+++ b/packages/markitdown/src/markitdown/_base_converter.py@@ -50,18 +50,18 @@ class DocumentConverter:) -> bool:"""Return a quick determination on if the converter should attempt converting the document.- This is primarily based `stream_info` (typically, `stream_info.mimetype`, `stream_info.extension`).- In cases where the data is retrieved via HTTP, the `steam_info.url` might also be referenced to+ This is primarily based on `stream_info` (typically, `stream_info.mimetype`, `stream_info.extension`).+ In cases where the data is retrieved via HTTP, the `stream_info.url` might also be referenced tomake a determination (e.g., special converters for Wikipedia, YouTube etc).- Finally, it is conceivable that the `stream_info.filename` might be used to in cases+ Finally, it is conceivable that the `stream_info.filename` might be used in caseswhere the filename is well-known (e.g., `Dockerfile`, `Makefile`, etc)NOTE: The method signature is designed to match that of the convert() method. This provides someassurance that, if accepts() returns True, the convert() method will also be able to handle the document.IMPORTANT: In rare cases, (e.g., OutlookMsgConverter) we need to read more from the stream to make a final- determination. Read operations inevitably advances the position in file_stream. In these case, the position- MUST be reset it MUST be reset before returning. This is because the convert() method may be called immediately+ determination. Read operations inevitably advance the position in file_stream. In these cases, the position+ MUST be reset before returning. This is because the convert() method may be called immediatelyafter accepts(), and will expect the file_stream to be at the original position.E.g.,@@ -71,7 +71,7 @@ class DocumentConverter:Parameters:- file_stream: The file-like object to convert. Must support seek(), tell(), and read() methods.- - stream_info: The StreamInfo object containing metadata about the file (mimetype, extension, charset, set)+ - stream_info: The StreamInfo object containing metadata about the file (mimetype, extension, charset, etc.)- kwargs: Additional keyword arguments for the converter.Returns:@@ -92,7 +92,7 @@ class DocumentConverter:Parameters:- file_stream: The file-like object to convert. Must support seek(), tell(), and read() methods.- - stream_info: The StreamInfo object containing metadata about the file (mimetype, extension, charset, set)+ - stream_info: The StreamInfo object containing metadata about the file (mimetype, extension, charset, etc.)- kwargs: Additional keyword arguments for the converter.Returns:diff --git a/packages/markitdown/src/markitdown/_exceptions.py b/packages/markitdown/src/markitdown/_exceptions.pyindex 2f87ac8b..cd5c5ec0 100644--- a/packages/markitdown/src/markitdown/_exceptions.py+++ b/packages/markitdown/src/markitdown/_exceptions.py@@ -2,9 +2,9 @@ from typing import Optional, List, AnyMISSING_DEPENDENCY_MESSAGE = """{converter} recognized the input as a potential {extension} file, but the dependencies needed to read {extension} files have not been installed. To resolve this error, include the optional dependency [{feature}] or [all] when installing MarkItDown. For example:-* pip install markitdown[{feature}]-* pip install markitdown[all]-* pip install markitdown[{feature}, ...]+* pip install 'markitdown[{feature}]'+* pip install 'markitdown[all]'+* pip install 'markitdown[{feature}, ...]'* etc."""@@ -41,7 +41,7 @@ class UnsupportedFormatException(MarkItDownException):class FailedConversionAttempt(object):"""- Represents an a single attempt to convert a file.+ Represents a single attempt to convert a file."""def __init__(self, converter: Any, exc_info: Optional[tuple] = None):diff --git a/packages/markitdown/src/markitdown/_markitdown.py b/packages/markitdown/src/markitdown/_markitdown.pyindex f6aa4df0..2b4f2a69 100644--- a/packages/markitdown/src/markitdown/_markitdown.py+++ b/packages/markitdown/src/markitdown/_markitdown.py@@ -270,7 +270,7 @@ class MarkItDown:warn(f"Plugin '{plugin}' failed to register converters:\n{tb}")self._plugins_enabled = Trueelse:- warn("Plugins converters are already enabled.", RuntimeWarning)+ warn("Plugin converters are already enabled.", RuntimeWarning)def convert(self,@@ -603,7 +603,7 @@ class MarkItDown:# Add the list of converters for nested processing_kwargs["_parent_converters"] = self._converters- # Add legaxy kwargs+ # Add legacy kwargsif stream_info is not None:if stream_info.extension is not None:_kwargs["file_extension"] = stream_info.extension@@ -654,7 +654,7 @@ class MarkItDown:)def register_page_converter(self, converter: DocumentConverter) -> None:- """DEPRECATED: User register_converter instead."""+ """DEPRECATED: Use register_converter instead."""warn("register_page_converter is deprecated. Use register_converter instead.",DeprecationWarning,@@ -671,9 +671,9 @@ class MarkItDown:Register a DocumentConverter with a given priority.Priorities work as follows: By default, most converters get priority- DocumentConverter.PRIORITY_SPECIFIC_FILE_FORMAT (== 0). The exception+ PRIORITY_SPECIFIC_FILE_FORMAT (== 0). The exceptionis the PlainTextConverter, HtmlConverter, and ZipConverter, which get- priority PRIORITY_SPECIFIC_FILE_FORMAT (== 10), with lower values+ priority PRIORITY_GENERIC_FILE_FORMAT (== 10), with lower valuesbeing tried first (i.e., higher priority).Just prior to conversion, the converters are sorted by priority, usingdiff --git a/packages/markitdown/src/markitdown/converters/_bing_serp_converter.py b/packages/markitdown/src/markitdown/converters/_bing_serp_converter.pyindex 6a383487..fd00a70a 100644--- a/packages/markitdown/src/markitdown/converters/_bing_serp_converter.py+++ b/packages/markitdown/src/markitdown/converters/_bing_serp_converter.py@@ -97,7 +97,7 @@ class BingSerpConverter(DocumentConverter):) # Python 3 doesn't care about extra paddingtry:- # RFC 4648 / Base64URL" variant, which uses "-" and "_"+ # RFC 4648 / Base64URL variant, which uses "-" and "_"a["href"] = base64.b64decode(u, altchars="-_").decode("utf-8")except UnicodeDecodeError:passdiff --git a/packages/markitdown/src/markitdown/converters/_cu_converter.py b/packages/markitdown/src/markitdown/converters/_cu_converter.pyindex e4080dda..230e3d86 100644--- a/packages/markitdown/src/markitdown/converters/_cu_converter.py+++ b/packages/markitdown/src/markitdown/converters/_cu_converter.py@@ -5,7 +5,7 @@ multi-modal extraction with structured field output. Supports documents,images, audio, and video. Fields are serialized as YAML front matter viathe CU SDK's ``to_llm_input()`` helper.-Install dependencies: ``pip install markitdown[az-content-understanding]``+Install dependencies: ``pip install 'markitdown[az-content-understanding]'``"""import sys@@ -474,7 +474,7 @@ class ContentUnderstandingConverter(DocumentConverter):raise MissingDependencyException("ContentUnderstandingConverter requires the optional dependency ""[az-content-understanding] (or [all]) to be installed. "- "E.g., `pip install markitdown[az-content-understanding]`"+ "E.g., `pip install 'markitdown[az-content-understanding]'`") from _dependency_exc_info[1].with_traceback( # type: ignore[union-attr]diff --git a/packages/markitdown/src/markitdown/converters/_doc_intel_converter.py b/packages/markitdown/src/markitdown/converters/_doc_intel_converter.pyindex fd843f23..adc94372 100644--- a/packages/markitdown/src/markitdown/converters/_doc_intel_converter.py+++ b/packages/markitdown/src/markitdown/converters/_doc_intel_converter.py@@ -165,7 +165,7 @@ class DocumentIntelligenceConverter(DocumentConverter):# unless explicitly requested.if _dependency_exc_info is not None:raise MissingDependencyException(- "DocumentIntelligenceConverter requires the optional dependency [az-doc-intel] (or [all]) to be installed. E.g., `pip install markitdown[az-doc-intel]`"+ "DocumentIntelligenceConverter requires the optional dependency [az-doc-intel] (or [all]) to be installed. E.g., `pip install 'markitdown[az-doc-intel]'`") from _dependency_exc_info[1].with_traceback( # type: ignore[union-attr]@@ -207,7 +207,7 @@ class DocumentIntelligenceConverter(DocumentConverter):def _analysis_features(self, stream_info: StreamInfo) -> List[str]:"""Helper needed to determine which analysis features to use.- Certain document analysis features are not availiable for+ Certain document analysis features are not available foroffice filetypes (.xlsx, .pptx, .html, .docx)"""mimetype = (stream_info.mimetype or "").lower()diff --git a/packages/markitdown/src/markitdown/converters/_docx_converter.py b/packages/markitdown/src/markitdown/converters/_docx_converter.pyindex 3975107b..0f92b9e6 100644--- a/packages/markitdown/src/markitdown/converters/_docx_converter.py+++ b/packages/markitdown/src/markitdown/converters/_docx_converter.py@@ -30,7 +30,7 @@ ACCEPTED_FILE_EXTENSIONS = [".docx"]class DocxConverter(HtmlConverter):"""- Converts DOCX files to Markdown. Style information (e.g.m headings) and tables are preserved where possible.+ Converts DOCX files to Markdown. Style information (e.g., headings) and tables are preserved where possible."""def __init__(self):diff --git a/packages/markitdown/src/markitdown/converters/_epub_converter.py b/packages/markitdown/src/markitdown/converters/_epub_converter.pyindex 3be65b01..82b01e25 100644--- a/packages/markitdown/src/markitdown/converters/_epub_converter.py+++ b/packages/markitdown/src/markitdown/converters/_epub_converter.py@@ -25,7 +25,7 @@ MIME_TYPE_MAPPING = {class EpubConverter(HtmlConverter):"""- Converts EPUB files to Markdown. Style information (e.g.m headings) and tables are preserved where possible.+ Converts EPUB files to Markdown. Style information (e.g., headings) and tables are preserved where possible."""def __init__(self):@@ -57,7 +57,7 @@ class EpubConverter(HtmlConverter):**kwargs: Any, # Options to pass to the converter) -> DocumentConverterResult:with zipfile.ZipFile(file_stream, "r") as z:- # Extracts metadata (title, authors, language, publisher, date, description, cover) from an EPUB file."""+ # Extracts metadata (title, authors, language, publisher, date, description, cover) from an EPUB file.# Locate content.opfcontainer_dom = minidom.parse(z.open("META-INF/container.xml"))diff --git a/packages/markitdown/src/markitdown/converters/_markdownify.py b/packages/markitdown/src/markitdown/converters/_markdownify.pyindex 19e8a298..8403b6b0 100644--- a/packages/markitdown/src/markitdown/converters/_markdownify.py+++ b/packages/markitdown/src/markitdown/converters/_markdownify.py@@ -43,7 +43,7 @@ class _CustomMarkdownify(markdownify.MarkdownConverter):convert_as_inline: Optional[bool] = False,**kwargs,):- """Same as usual converter, but removes Javascript links and escapes URIs."""+ """Same as usual converter, but removes JavaScript links and escapes URIs."""prefix, suffix, text = markdownify.chomp(text) # type: ignoreif not text:return ""diff --git a/packages/markitdown/src/markitdown/converters/_outlook_msg_converter.py b/packages/markitdown/src/markitdown/converters/_outlook_msg_converter.pyindex d216beae..7717f62d 100644--- a/packages/markitdown/src/markitdown/converters/_outlook_msg_converter.py+++ b/packages/markitdown/src/markitdown/converters/_outlook_msg_converter.py@@ -54,7 +54,7 @@ class OutlookMsgConverter(DocumentConverter):finally:file_stream.seek(cur_pos)- # Brue force, check if it's an Outlook file+ # Brute force, check if it's an Outlook filetry:if olefile is not None:msg = olefile.OleFileIO(file_stream)diff --git a/packages/markitdown/src/markitdown/converters/_transcribe_audio.py b/packages/markitdown/src/markitdown/converters/_transcribe_audio.pyindex d558e462..df2fd76f 100644--- a/packages/markitdown/src/markitdown/converters/_transcribe_audio.py+++ b/packages/markitdown/src/markitdown/converters/_transcribe_audio.py@@ -24,7 +24,10 @@ def transcribe_audio(file_stream: BinaryIO, *, audio_format: str = "wav") -> str# Check for installed dependenciesif _dependency_exc_info is not None:raise MissingDependencyException(- "Speech transcription requires installing MarkItdown with the [audio-transcription] optional dependencies. E.g., `pip install markitdown[audio-transcription]` or `pip install markitdown[all]`"+ "Speech transcription requires installing MarkItDown with the "+ "[audio-transcription] optional dependencies. E.g., "+ "`pip install 'markitdown[audio-transcription]'` or "+ "`pip install 'markitdown[all]'`") from _dependency_exc_info[1].with_traceback( # type: ignore[union-attr]diff --git a/packages/markitdown/tests/test_cli_vectors.py b/packages/markitdown/tests/test_cli_vectors.pyindex 5add530b..547c7c00 100644--- a/packages/markitdown/tests/test_cli_vectors.py+++ b/packages/markitdown/tests/test_cli_vectors.py@@ -96,7 +96,7 @@ def test_output_to_file(shared_tmp_dir, test_vector) -> None:@pytest.mark.parametrize("test_vector", CLI_TEST_VECTORS)def test_input_from_stdin_without_hints(shared_tmp_dir, test_vector) -> None:- """Test that the CLI readds from stdin correctly."""+ """Test that the CLI reads from stdin correctly."""test_input = b""with open(os.path.join(TEST_FILES_DIR, test_vector.filename), "rb") as stream:diff --git a/packages/markitdown/tests/test_module_misc.py b/packages/markitdown/tests/test_module_misc.pyindex 91d7b52c..f966eee1 100644--- a/packages/markitdown/tests/test_module_misc.py+++ b/packages/markitdown/tests/test_module_misc.py@@ -126,7 +126,7 @@ def test_stream_info_operations() -> None:**{keyword: f"{keyword}.2"})- # Make sure the targted attribute is updated+ # Make sure the targeted attribute is updatedassert getattr(updated_stream_info, keyword) == f"{keyword}.2"# Make sure the other attributes are unchanged@@ -143,7 +143,7 @@ def test_stream_info_operations() -> None:StreamInfo(**{keyword: f"{keyword}.2"}))- # Make sure the targted attribute is updated+ # Make sure the targeted attribute is updatedassert getattr(updated_stream_info, keyword) == f"{keyword}.2"# Make sure the other attributes are unchanged