{"id":2432,"date":"2026-11-15T15:38:26","date_gmt":"2026-11-15T07:38:26","guid":{"rendered":"https:\/\/xlwings.net\/blog\/?p=2432"},"modified":"2026-03-29T10:42:03","modified_gmt":"2026-03-29T10:42:03","slug":"how-to-use-rangesortspecial-in-the-xlwings-api-way","status":"publish","type":"post","link":"https:\/\/xlwings.net\/blog\/how-to-use-rangesortspecial-in-the-xlwings-api-way\/","title":{"rendered":"How to use Range.SortSpecial in the xlwings API way"},"content":{"rendered":"\n<p class=\"wp-block-paragraph\">The <code>SortSpecial<\/code> method in the <code>Range<\/code> object is a powerful feature for sorting data in Excel, particularly when dealing with custom lists or locale-specific sorting rules, such as those for East Asian languages. In xlwings, this method provides programmatic access to Excel&#8217;s advanced sorting capabilities, allowing for more nuanced sorting beyond simple alphabetical or numerical order. It is especially useful for sorting by custom lists (e.g., days of the week, months) or when sorting data in languages that use specific character orders, like Japanese or Chinese.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">The xlwings API syntax for <code>SortSpecial<\/code> closely mirrors the VBA method, with parameters that control the sorting behavior. The method is called on a <code>Range<\/code> object, and its parameters define the sort order, key, and other options. The general syntax in xlwings is:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>range_object.api.SortSpecial(SortMethod, Key1, Order1, Type, Key2, Order2, Key3, Order3, Header, OrderCustom, MatchCase, Orientation, SortMethod, DataOption1, DataOption2, DataOption3)<\/code><\/pre>\n\n\n\n<p class=\"wp-block-paragraph\">Key parameters include:<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li><code>SortMethod<\/code>: Specifies the type of sort. Use <code>xlSortMethodPinYin<\/code> for phonetic sorting in East Asian languages or <code>xlSortMethodStroke<\/code> for stroke count sorting in Chinese. In xlwings, these constants are available via <code>xlwings.constants<\/code> (e.g., <code>xlwings.constants.xlSortMethodPinYin<\/code>).<\/li>\n\n\n\n<li><code>Key1<\/code>, <code>Key2<\/code>, <code>Key3<\/code>: The ranges that define the columns or rows to sort by, specified as strings (e.g., &#8220;A1&#8221; for a column). In xlwings, you can pass a <code>Range<\/code> object or a string.<\/li>\n\n\n\n<li><code>Order1<\/code>, <code>Order2<\/code>, <code>Order3<\/code>: Determine the sort order for each key, using constants like <code>xlAscending<\/code> (for ascending order) or <code>xlDescending<\/code> (for descending), accessible via <code>xlwings.constants<\/code>.<\/li>\n\n\n\n<li><code>Header<\/code>: Indicates whether the range has headers. Use <code>xlYes<\/code>, <code>xlNo<\/code>, or <code>xlGuess<\/code> from <code>xlwings.constants<\/code>.<\/li>\n\n\n\n<li><code>OrderCustom<\/code>: An integer specifying a custom sort order from Excel&#8217;s custom lists (e.g., 1 for the default list).<\/li>\n<\/ul>\n\n\n\n<p class=\"wp-block-paragraph\">For example, to sort a range by a custom list (like months) in ascending order, you might set <code>OrderCustom<\/code> to the index of that list. Note that many parameters are optional and can be omitted by passing <code>None<\/code> in Python.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Here is an xlwings code example that demonstrates using <code>SortSpecial<\/code> to sort a range by a custom list. Assume we have an Excel workbook with data in range &#8220;A1:B10&#8221;, where column A contains month names (e.g., &#8220;January&#8221;, &#8220;February&#8221;) and column B has corresponding values. We want to sort by column A using the default month order:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>import xlwings as xw\n\n# Connect to the active workbook and sheet\napp = xw.apps.active\nwb = app.books.active\nsheet = wb.sheets.active\n\n# Define the range to sort (including headers)\nsort_range = sheet.range(\"A1:B10\")\n\n# Perform the sort using SortSpecial with a custom order (months)\nsort_range.api.SortSpecial(\nSortMethod=xw.constants.xlSortMethodPinYin, # Use phonetic sorting, but custom list overrides\nKey1=sheet.range(\"A1\"), # Sort by column A\nOrder1=xw.constants.xlAscending,\nHeader=xw.constants.xlYes, # Range has headers\nOrderCustom=1 # Use the first custom list (typically months in English versions)\n)<\/code><\/pre>\n\n\n\n<p class=\"wp-block-paragraph\"><\/p>\n","protected":false},"excerpt":{"rendered":"<p>The `SortSpecial` method in the `Range` object is a powerful feature for sorting data in Excel, part&#8230;<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[25],"tags":[],"class_list":["post-2432","post","type-post","status-publish","format-standard","hentry","category-xlwings-api-reference"],"_links":{"self":[{"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/posts\/2432","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/comments?post=2432"}],"version-history":[{"count":1,"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/posts\/2432\/revisions"}],"predecessor-version":[{"id":3693,"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/posts\/2432\/revisions\/3693"}],"wp:attachment":[{"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/media?parent=2432"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/categories?post=2432"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/tags?post=2432"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}