ASPPY is a Python-based runtime that executes Classic ASP (VBScript) pages. It provides compatibility with most VBScript built-in functions, the Classic ASP object model (Request, Response, Session, Application, Server), and various COM components commonly used in legacy ASP applications.

Platform Support

ASPPY works on:

• Windows
• Linux
• macOS

Dependencies

The following Python libraries are required:

VBScript Built-in Functions

Compatibility notes for built-ins:

• ASPPY targets practical Classic ASP/VBScript compatibility, but does not guarantee byte-for-byte parity with IIS VBScript for every edge case.
• The function lists below describe the exposed runtime surface; behavior can still differ in locale, coercion, error wording, and edge conditions.
• Functions implemented through compatibility shims/stubs (for example formatting/script-engine helpers) are intended for app portability, not strict engine emulation.
• SQL/dialect translation is intentionally out of scope; database commands are executed as provided by the script and underlying provider/driver.
• If exact behavior matters for a critical path, validate with your app-specific regression tests.

String Functions

Array Functions

Type Conversion Functions

Date/Time Functions

Date Constants

Math Functions

Format Functions

Note: formatting functions are compatibility-focused and may differ from IIS under some locale/regional settings.

Information Functions

Note: type/coercion semantics generally follow VBScript, but may differ in edge cases involving Empty/Null/Nothing and host objects.

VarType Constants

Color Functions

Classic ASP Objects

Server-Side Includes

<!--#include file="..." --> and <!--#include virtual="..." --> are resolved before the page runs. The two forms differ only in what the path is relative to:

Matching IIS, the scanner accepts backslashes as separators, ./ and ../ segments, single or double quotes, and loose whitespace around #include and =. Paths that climb above the application root are refused.

A file included twice is expanded twice. The directive is a textual splice, not an idempotent import, so including a snippet at two points in a page emits it at both — there is no #pragma once behaviour and no de-duplication. That also applies when the same file is reached by two different spellings (file= in one place, virtual= in another), or directly in one place and transitively through another include. Because definitions are hoisted before execution, a duplicated include that declares a Sub or Function does not raise a redefinition error; only its top-level statements and markup repeat.

A genuine cycle — a.inc including b.inc including a.inc — is an error, not a silently truncated expansion, and fails the request as IIS does. Detection walks the current include chain, which is what keeps legitimate repeats working; nesting deeper than 32 levels is also refused.

Text that merely looks like a directive is left alone: #include inside a VBScript string literal or inside an ASP comment is inert.

Server Object

Methods

Properties

Extension Methods (ASPPY-specific)

Supported Server.CreateObject ProgIDs

• Scripting.Dictionary
• Scripting.FileSystemObject
• ADODB.Connection, ADODB.Recordset, ADODB.Command, ADODB.Stream
• VBScript.RegExp / RegExp
• MSXML2.ServerXMLHTTP, MSXML2.XMLHTTP, MSXML2.DOMDocument (incl. .3.0/.6.0 aliases)
• Microsoft.XMLDOM, MSXML.DOMDocument
• CDO.Message, CDOSYS.Message
• ASPPY.POP3, ASPPY.POP3, ASPPY.IMAP, ASPPY.IMAP

Request Object

Properties

Methods

HTTP methods and body parsing

• ASPPY passes through HTTP methods to ASP pages without a verb allow-list.
• Request.ServerVariables("REQUEST_METHOD") returns the incoming verb string (for example: GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS).
• Request.Form is parsed for POST with supported form encodings (application/x-www-form-urlencoded, multipart/form-data).
• For non-POST bodies (PUT, DELETE, PATCH, etc.), read raw bytes via Request.BinaryRead(...); Request.Form remains empty.
• Request.TotalBytes reflects the request body size for any method.

Request.Files Collection

Access uploaded files from multipart form submissions.

' Iterate over all uploaded files
For Each file In Request.Files
    Response.Write(file.FileName)
    Response.Write(file.Size)
    Response.Write(file.ContentType)
    ' Save to disk
    file.SaveAs Server.MapPath("/uploads/" & file.FileName)
Next

' Access specific file
Set f = Request.Files("myfile")
If Not f Is Nothing Then
    Response.Write f.Name
    Response.Write f.FileName
    Response.Write f.Size
    Response.Write f.ContentType
End If

' Check if file exists
If Request.Files.Exists("myfile") Then
    ' File was uploaded
End If

' Get count
Response.Write Request.Files.Count

UploadedFile Properties

UploadedFile Methods

Files Collection Methods

Response Object

Properties

Methods

Session Object

Properties

Methods

Application Object

Properties

Methods

ASPPY Extended Objects

ASPPY Object

The ASPPY object provides additional functionality beyond classic ASP.

It is available as global ASPPY in script scope.

How members are named

Member access is always case-insensitive, so casing never matters. The shape of a name follows one rule:

Objects that exist on IIS use PascalCase. Wrappers around a third-party library keep that library's own names, so its documentation transfers unchanged.

If a member name is wrong, error 438 names the closest match rather than leaving you to guess: Unknown member: SETMARGINZ on PdfDoc (did you mean 'SetMargins'?).

Members beginning with _ are host-side internals. VBScript identifiers cannot start with an underscore, so they are unreachable from script and, like on IIS, raise 438.

JSON

ASPPY.JSON.Encode(value[, pretty])  ' Returns JSON string
ASPPY.JSON.Decode(json_string)      ' Returns VBScript value

Note: member access is case-insensitive in VBScript; runtime members are exposed as json, zip, image, crypto, pdf.

ZIP

ASPPY.Zip.Zip(path[, out_path])     ' Creates a ZIP file
ASPPY.Zip.Unzip(zip_path, dest_folder[, overwrite])  ' Extracts a ZIP file

Image (Pillow)

ASPPY.Image.open(path)               ' Opens an image file
ASPPY.Image.new(mode, size, color)    ' Creates a new image
ASPPY.Image.merge(mode, bands)       ' Merges image bands
ASPPY.Image.blend(img1, img2, alpha) ' Blends two images
ASPPY.Image.composite(img1, img2, mask) ' Creates composite

ASPPY.ImageDraw.Draw(img)            ' Creates a draw object
ASPPY.ImageFilter.BLUR               ' Blur filter constant
ASPPY.ImageFilter.CONTOUR            ' Contour filter
ASPPY.ImageFilter.EDGE_ENHANCE       ' Edge enhancement
ASPPY.ImageFilter.SHARPEN            ' Sharpen filter
ASPPY.ImageFilter.GaussianBlur(radius) ' Gaussian blur

ASPPY.ImageEnhance.Brightness(img)   ' Brightness enhancer
ASPPY.ImageEnhance.Contrast(img)     ' Contrast enhancer

ImageInstance Properties/Methods

PDF (FPDF)

Set pdf = ASPPY.Pdf.New([orientation[, unit[, format]]])

PdfDoc Methods

Crypto (bcrypt)

ASPPY.Crypto.Hash(password[, rounds])    ' Hashes a password (rounds 4-31, default 12)
ASPPY.Crypto.Verify(password, hashed)     ' Verifies password against hash

ExecutePython

ASPPY.ExecutePython(code [, args] [, timeout])       ' Executes inline Python source, returns ASPPY_RETURN value as string
ASPPY.ExecutePythonFile(path [, args] [, timeout])   ' Executes a .py file (relative to docroot), returns ASPPY_RETURN value

Enable with environment variable ASP_PY_ALLOW_PYTHON=1. Each call spawns an isolated Python subprocess. The Python snippet uses ASPPY_RETURN(value) to return a string to VBScript.

Both optional arguments work the same way on either method. args takes any JSON-encodable value (string, number, boolean, Array, Scripting.Dictionary, or a nesting of those) and the Python side reads it as the built-in ASPPY_ARGS, already decoded — it is None when the argument is omitted. timeout is a per-call limit in seconds that overrides ASP_PY_PYTHON_TIMEOUT. See the ASPPY.ExecutePython page for full documentation, samples, and environment variables.

COM Objects

Scripting.Dictionary

Set dict = Server.CreateObject("Scripting.Dictionary")

Scripting.FileSystemObject

Set fso = Server.CreateObject("Scripting.FileSystemObject")

File Object

Folder Object

TextStream Object

VBScript.RegExp

Set regex = Server.CreateObject("VBScript.RegExp")

ADODB.Connection

Set conn = Server.CreateObject("ADODB.Connection")

Connection string notes:

• Execution support is currently SQLite (sqlite3), Access (pyodbc + Access ODBC driver), Excel (pyodbc + Excel ODBC driver), and generic ODBC (pyodbc) in this runtime.
• ASPPY now parses and classifies common legacy ADO connection string families (Access, SQL Server, ODBC, MySQL, Oracle, PostgreSQL) so unsupported providers fail with explicit migration guidance instead of generic errors.
• For SQLite, use Provider=SQLite;Data Source=<path> (or Provider=SQLite;Database=<path>), or a bare file path.
• For Access, use legacy Access-style strings (Provider=Microsoft.Jet.OLEDB.4.0 / Provider=Microsoft.ACE.OLEDB.12.0) with Data Source=<path to .mdb/.accdb>.
• For Excel, use legacy Excel-style strings (for example Provider=Microsoft.ACE.OLEDB.12.0;Data Source=<path>;Extended Properties="Excel 12.0 Xml;HDR=YES;IMEX=1";).
• Excel support is currently read-only in ASPPY (SELECT queries only).
• For ODBC, use DSN=...;Uid=...;Pwd=...; or Driver={...};Server=...;Database=...;Uid=...;Pwd=...;.
• PostgreSQL is supported via ODBC (Provider=PostgreSQL;Server=...;Database=...;User Id=...;Password=...;Port=5432;) or explicit Driver={PostgreSQL ...} / DSN=....
• SQL dialect translation is not performed; application SQL is executed as-is by the selected provider/driver.
• Internally, provider adapters now use a registry + capability flags, so future DBMS support can be added as pluggable adapters without changing the ADO surface API.

ADODB.Recordset

Set rs = Server.CreateObject("ADODB.Recordset")

GetString

Reads forward from the current row and leaves the recordset at EOF (or just past the last row taken), as ADO does. Omitted arguments take the ADO defaults: TAB between columns, CR between rows, "" for Null. Every row is terminated, including the last.

' Pipe-separated, CRLF-terminated, empty string for NULL
gs = rs.GetString(, , "|", vbCrLf, "")

StringFormat only has one legal value, adClipString (2); anything else raises.

Bookmark

ASPPY recordsets are client-side cursors over an in-memory row list, so bookmarks are always available and are the row's ordinal. Assigning a bookmark outside the recordset raises rather than moving anywhere.

Divergence worth knowing: on IIS, bookmark support depends on the provider and cursor — a Jet OpenSchema recordset reports Supports(adBookmark) = False. ASPPY supports them everywhere, so code guarded by If rs.Supports(adBookmark) takes the enabled branch here and the disabled one there.

OpenSchema

Returns schema information as a Recordset, with the OLE DB rowset column names, so rs("TABLE_NAME") works as it does on IIS. Supported SchemaEnum values:

Set rs = conn.OpenSchema(20)                              ' every table
Set rs = conn.OpenSchema(20, Array(Empty, Empty, "widget"))  ' one table
Set rs = conn.OpenSchema(4,  Array(Empty, Empty, "widget"))  ' its columns

criteria is an array of restriction values positionally matched to the rowset's restriction columns; Empty entries mean "no restriction". Any other queryType raises rather than returning an empty recordset. System tables are excluded.

ADODB.Field

Reached through rs.Fields(n), rs.Fields("name") or rs("name"). Its default property is Value, so a Field reads as its value in any expression.

ADODB.Command

Set cmd = Server.CreateObject("ADODB.Command")

Parameter objects returned by CreateParameter expose Name, Type, Direction, Size, Value, Precision, NumericScale, Attributes and Properties.

The Properties collections

Connection, Command, Recordset, Field and Parameter all expose a Properties collection so that obj.Properties.Count runs instead of raising error 438. It is always empty: those entries are OLE DB provider properties, and ASPPY talks to SQLite and ODBC directly rather than through a provider. IIS reports 14 on an unopened Connection, around 94 once it is opened against Jet, and 88 on a connected Command. Anything that enumerates them, or reads a specific provider property by name, will not find it.

ADODB.Parameter / Parameters

ADODB.Stream

Set stream = Server.CreateObject("ADODB.Stream")

Byte order marks, Size and Position

A text stream is measured in bytes, and ADO writes a byte order mark for the Unicode encodings. Verified against IIS by writing 16 characters plus one LF and reading the buffer back as binary:

The BOM appears only once there is content: an open but empty stream has Size 0. Size, Position, Read, CopyTo, SaveToFile and switching Type to binary all share the same byte view, so at end of stream Position equals Size, and the file written by SaveToFile is byte-for-byte what Read returns.

This matters in practice: ADODB.Stream plus SaveToFile is the usual way Classic ASP produces UTF-8 CSV and XML, and consumers — Excel above all — rely on the BOM being there.

Known limitation. ReadText and SkipLine still index the buffer by character internally. For single-byte charsets and for ASCII text that is indistinguishable from the byte offset; it can differ for multi-byte content in the middle of a stream.

MSXML2 Objects

ServerXMLHTTP

Set http = Server.CreateObject("MSXML2.ServerXMLHTTP")

Binary payloads are a Byte() SafeArray

ResponseBody, Request.BinaryRead and ADODB.Stream.Read return a byte array, matching IIS exactly:

objStream.Write http.ResponseBody and Response.BinaryWrite accept it unchanged.

XMLHTTP

Set http = Server.CreateObject("MSXML2.XMLHTTP")

Same interface as ServerXMLHTTP.

DOMDocument

Set xml = Server.CreateObject("MSXML2.DOMDocument")

Node model notes

• Nothing, not Empty. A lookup that finds nothing — selectSingleNode, getAttributeNode, parentNode at the document level — returns Nothing, so the standard If Not n Is Nothing Then guard works.
• childNodes includes text. Text and CDATA appear as real nodes with nodeType 3 and 4, so node.firstChild.nodeValue reads an element's content and Do While n.nodeType = 3 : Set n = n.nextSibling : Loop terminates.
• Fragments splice. appendChild(fragment) inserts the fragment's children and discards the wrapper.
• save() writes anywhere inside the application root by default — xmlDoc.save Server.MapPath("out.xml") just works. Writing outside it requires ASP_PY_XML_ALLOW_LOCAL=1.

XPath, XSLT and the optional lxml package

Python's bundled XML parser has no XSLT engine and only a small XPath subset, so those features come from lxml, which is optional in the same way fpdf2, Pillow and bcrypt are:

pip install lxml

An unsupported XPath raises rather than returning an empty node list. Silently returning zero matches — which is what the stdlib parser does for anything outside its subset, including every namespaced document — is far harder to diagnose than an error.

Namespace prefixes in an XPath resolve from the document's own declarations, and from setProperty "SelectionNamespaces", "xmlns:a='urn:x'".

Deliberate divergences

• External DTDs are never fetched. MSXML downloads the DTD named in a DOCTYPE and validates against it; ASPPY does not touch the network while parsing. A document MSXML rejects because the remote DTD failed to validate will parse here. Internal DTD subsets are accepted by both.
• Entities are not expanded. <!ENTITY x SYSTEM "file:///..."> stays literal instead of inlining the file, so the classic XXE read does not work.
• TLS verification cannot be turned off. setOption 2 (SXH_OPTION_IGNORE_SERVER_SSL_CERT_ERROR_FLAGS) is recorded and readable via getOption, but certificate and hostname checks stay on.
• Requests to localhost and private networks are blocked unless ASP_PY_ALLOW_LOCALHOST=1 / ASP_PY_ALLOW_PRIVATE_NETS=1. See Runtime Environment Variables.

WScript.Shell

Set wsh = Server.CreateObject("WScript.Shell")

IWshShortcut exposes TargetPath, Arguments, WorkingDirectory, Description, IconLocation, WindowStyle, Hotkey, FullName and Save. IWshURLShortcut exposes TargetPath, FullName and Save, and re-opening an existing .url reads its target back.

The .lnk writer builds a real [MS-SHLLINK] file — header, LinkTargetIDList, LinkInfo and the string blocks — rather than calling the Shell COM object, so the same code path runs on a non-Windows host. Shortcuts written by ASPPY were verified by reading them back through Windows' own WScript.Shell: every property round-trips and Explorer resolves the target. On a non-Windows host the LinkTargetIDList is omitted (it is produced by the Windows shell), which leaves a link Windows can parse but not resolve.

Deliberate divergences

• Run and Exec are not implemented. They execute arbitrary shell commands from a web request, which contradicts the sandboxing ASPPY applies elsewhere — FileSystemObject is confined to the docroot, and ADODB.Stream to ASP_PY_ADO_ROOT. They raise ActiveX error 429, which On Error Resume Next can detect, rather than failing silently.
• RegWrite and RegDelete are not implemented for the same reason. RegRead is available because it cannot change machine state.

CDO.Message

Set msg = Server.CreateObject("CDO.Message")

ASPPY.POP3

Set pop = Server.CreateObject("ASPPY.POP3")

ASPPY.IMAP

Set imap = Server.CreateObject("ASPPY.IMAP")

Runtime Environment Variables

Runtime Error Parity

Err.Number is the contract ASPPY holds itself to: it is checked case by case against a live IIS 10 / VBScript 10.8 installation, because it is locale-independent and it is what real code branches on (If Err.Number = 9 Then). Behaviours verified against IIS include:

Err.Number is a signed 32-bit Long, so an HRESULT such as 0x80004005 reports as -2147467259 - never as 2147500037. This holds for Err.Raise &H80004005 too.

Deliberate divergences

• Err.Description text. IIS localises descriptions - a Dutch server returns "Het subscript valt buiten het bereik" for error 9 - so there is no single IIS string to match. ASPPY always emits English, and appends diagnostic detail IIS omits (Subscript out of range: ARR(9), UBound = 2; Unknown member: SETMARGINZ on PdfDoc (did you mean 'SetMargins'?)). Branch on Err.Number, never on description text.
• Server.MapPath("../"). IIS resolves paths that escape the web root and returns them. ASPPY refuses, because on IIS the result is only safe thanks to filesystem ACLs that ASPPY cannot rely on. This is a hardening, and the one case where ASPPY is deliberately stricter than IIS.
• Host-object internals. ASPPY's objects are Python classes, so they have members the COM originals do not. Every such member is prefixed with _, which VBScript identifiers cannot name, so Response.finalize_headers and Session.CodePage_ raise error 438 exactly as they do on IIS.

VBScript Compatibility Notes

• UBound/LBound: follow VBScript-like array allocation rules; uninitialized/invalid-array usage raises runtime errors. See Runtime Error Parity for the exact ReDim / empty-array rules.
• VBScript.RegExp.Replace: supports VB-style replacement tokens ($1, $&, $`, $', $$).
• Request.Form: parsed for POST only; non-POST bodies are available via Request.BinaryRead.
• Date/number formatting is locale-aware across 60 locales and verified against live IIS; see Localization for the supported list and the documented divergences.

Localization

ASPPY implements the Classic ASP locale model for 60 locales, driven by a generated table (ASPPY/locale_data.json) extracted from the Windows NLS data and validated field-by-field against live IIS output.

What is locale-aware

Deliberate divergences

• Default locale. With no locale set, ASPPY uses LCID 1033 (en-US) rather than inheriting the host's system locale, so output is identical on every machine. Same reasoning as the UTF-8 default below.
• CStr(date) / implicit date-to-string. While no locale has been selected, ASPPY keeps its ISO output (2024-03-05 14:07:09) instead of the IIS locale general date. This protects the very common pattern of concatenating a date straight into SQL. As soon as an app opts in via Session.LCID, SetLocale or <%@ LCID %>, full IIS formatting applies.
• Non-Gregorian calendars. ar-SA and th-TH render dates on the Gregorian calendar, so their era and year differ from IIS (which uses Hijri and the Buddhist era). Separators, names, currency and number formatting are correct for both. All other 58 locales match IIS exactly.
• CStr(True) returns "True". IIS localises boolean literals via the OS user locale, which is a property of the host rather than of the script.

Supported locales

en-US, en-GB, en-AU, en-CA · fr-FR, fr-BE, fr-CA, fr-CH · de-DE, de-CH, de-AT · nl-NL, nl-BE · es-ES (both sort orders), es-MX · it-IT, it-CH · pt-PT, pt-BR · ca-ES, gl-ES, eu-ES · sv-SE, sv-FI, da-DK, fi-FI, nb-NO, nn-NO, is-IS · pl-PL, cs-CZ, sk-SK, hu-HU, sl-SI, hr-HR, ro-RO, bg-BG, ru-RU, uk-UA, el-GR, tr-TR, et-EE, lv-LV, lt-LT · ja-JP, ko-KR, zh-CN, zh-TW, zh-HK · ar-SA, ar-DZ, he-IL, hi-IN, th-TH, id-ID, ms-MY, vi-VN, kk-KZ, uz-Latn-UZ.

Character Encoding

ASPPY defaults to UTF-8 (codepage 65001) everywhere. This is an intentional break from IIS.

Classic ASP under IIS inherits the system ANSI codepage of the host machine - typically 1252 on a Western Windows server, 932 on a Japanese one. ASPPY does not, for three reasons:

• ASPPY runs on Linux and macOS, where "the system ANSI codepage" has no meaningful equivalent - there is no coherent host default to inherit.
• Modern consumers (browsers, fetch, JSON APIs, HTML5) assume UTF-8.
• VBScript strings are Unicode internally. UTF-8 is the only encoding that round-trips them losslessly; legacy codepages silently substitute characters they cannot represent.

Migration impact

Pages served as windows-1252 under IIS are served as UTF-8 by ASPPY and labelled as such in the Content-Type header, so browsers render them correctly with no source change. Legacy .asp files saved in windows-1252 need no conversion - ASPPY detects and decodes them automatically.

Intervention is only required where a non-browser consumer expects legacy bytes: CSV exports opened in Excel, fixed-format files for banking or EDI partners, or older integration endpoints that assume iso-8859-1. Set the encoding explicitly on those responses:

Response.Charset = "windows-1252"

Compatibility Matrix

Global.asa Support

ASPPY supports the Global.asa file with the following events:

• Application_OnStart
• Application_OnEnd
• Session_OnStart
• Session_OnEnd

Example Global.asa:

<script language="vbscript" runat="server">
Sub Application_OnStart
    Application("StartTime") = Now()
End Sub

Sub Session_OnStart
    Session("UserID") = ""
End Sub
</script>

Running ASPPY

Start the built-in server:

python -m ASPPY.server [host] [port] [docroot]

Example:

python -m ASPPY.server 0.0.0.0 8080 www

The server will serve both static files and .asp pages from the specified document root.