{"id":2328,"date":"2026-09-24T15:53:48","date_gmt":"2026-09-24T07:53:48","guid":{"rendered":"https:\/\/xlwings.net\/blog\/?p=2328"},"modified":"2026-03-28T13:13:08","modified_gmt":"2026-03-28T13:13:08","slug":"how-to-use-worksheetlistobjects-in-the-xlwings-api-way","status":"publish","type":"post","link":"https:\/\/xlwings.net\/blog\/how-to-use-worksheetlistobjects-in-the-xlwings-api-way\/","title":{"rendered":"How to use Worksheet.ListObjects in the xlwings API way"},"content":{"rendered":"\n<p class=\"wp-block-paragraph\">In Excel, the <code>ListObjects<\/code> collection represents all the tables (<code>ListObject<\/code>) on a specific worksheet. Tables are powerful features for managing and analyzing structured data, offering built-in filtering, sorting, and easy referencing. Through the <code>ListObjects<\/code> property of a <code>Worksheet<\/code> object in xlwings, you can programmatically access, create, and manipulate these tables, enabling automation of data organization and analysis tasks.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\"><strong>Functionality:<\/strong><br>The <code>ListObjects<\/code> property provides access to the collection of tables within a worksheet. You can use it to:<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li>Retrieve a specific table by its name or index.<\/li>\n\n\n\n<li>Iterate through all tables to perform batch operations.<\/li>\n\n\n\n<li>Add new tables based on a given range of data.<\/li>\n\n\n\n<li>Check the number of tables present.<\/li>\n<\/ul>\n\n\n\n<p class=\"wp-block-paragraph\"><strong>Syntax:<\/strong><br>In xlwings, the <code>ListObjects<\/code> property is accessed from a <code>Worksheet<\/code> object. The general call format is:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>worksheet.api.ListObjects<\/code><\/pre>\n\n\n\n<p class=\"wp-block-paragraph\">This returns a COM object representing the Excel <code>ListObjects<\/code> collection. To work with it more intuitively in xlwings, you often use methods like <code>add()<\/code> or access items directly.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">To create a new table:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>worksheet.api.ListObjects.Add(SourceType, Source, LinkSource, HasHeaders, Destination)<\/code><\/pre>\n\n\n\n<ul class=\"wp-block-list\">\n<li><code>SourceType<\/code>: Specifies the source of the data. Typically use <code>1<\/code> (xlSrcRange) for a worksheet range.<\/li>\n\n\n\n<li><code>Source<\/code>: The range address as a string (e.g., &#8220;A1:D10&#8221;) or an xlwings Range object.<\/li>\n\n\n\n<li><code>LinkSource<\/code>: Usually <code>False<\/code> for data within the workbook.<\/li>\n\n\n\n<li><code>HasHeaders<\/code>: Set to <code>True<\/code> if the range includes headers; <code>False<\/code> otherwise.<\/li>\n\n\n\n<li><code>Destination<\/code>: Optional; used if <code>SourceType<\/code> is <code>xlSrcExternal<\/code>. Can be omitted for range sources.<\/li>\n<\/ul>\n\n\n\n<p class=\"wp-block-paragraph\">To reference an existing table by name:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>table = worksheet.api.ListObjects(\"TableName\")<\/code><\/pre>\n\n\n\n<p class=\"wp-block-paragraph\"><strong>Example:<\/strong><br>Consider a worksheet with sales data in the range A1:C5. The following xlwings code demonstrates using <code>ListObjects<\/code> to create a table, access its properties, and iterate through tables.<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>import xlwings as xw\n\n# Connect to the active workbook and worksheet\nwb = xw.Book.active\nws = wb.sheets&#91;'Sheet1']\n\n# Create a table from the range A1:C5\nsource_range = ws.range('A1:C5')\ntable = ws.api.ListObjects.Add(\nSourceType=1, # xlSrcRange\nSource=source_range.api,\nLinkSource=False,\nHasHeaders=True,\nDestination=None\n)\ntable.Name = 'SalesTable' # Set a name for the table\n\n# Access the table by name\nsales_table = ws.api.ListObjects('SalesTable')\nprint(f\"Table range: {sales_table.Range.Address}\")\n\n# Iterate through all tables in the worksheet\nfor tbl in ws.api.ListObjects:\n    print(f\"Found table: {tbl.Name}\")\n\n# Count the number of tables\ntable_count = ws.api.ListObjects.Count\nprint(f\"Total tables: {table_count}\")\n\n# Add a total row to the table\nsales_table.ShowTotals = True\nsales_table.ListColumns(3).TotalsCalculation = -4157 # xlTotalsCalculationSum\n\n# Resize the table to include new data (e.g., extending to row 6)\nsales_table.Resize(ws.range('A1:C6').api)<\/code><\/pre>\n\n\n\n<p class=\"wp-block-paragraph\"><\/p>\n","protected":false},"excerpt":{"rendered":"<p>In Excel, the `ListObjects` collection represents all the tables (`ListObject`) on a specific worksh&#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-2328","post","type-post","status-publish","format-standard","hentry","category-xlwings-api-reference"],"_links":{"self":[{"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/posts\/2328","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=2328"}],"version-history":[{"count":1,"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/posts\/2328\/revisions"}],"predecessor-version":[{"id":3548,"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/posts\/2328\/revisions\/3548"}],"wp:attachment":[{"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/media?parent=2328"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/categories?post=2328"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/tags?post=2328"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}