Fork me on GitHub

Read what you need

Transcrypt 3.7 Documentation

Focus is on the features that are unique for Transcrypt, rather than the general features of Python. You'll find command line options, pragmas (local compiler options) and systematic code examples demonstrating all supported features. In addition you'll find examples showing how to combine Transcrypt with html and with a number of popular JavaScript libraries and platforms. Although the demo's on this site will get you started, if you plan to use Transcrypt for production, spending some time with the documentation is likely to pay off.

Trancrypt 3.7 FAQ

Answers to some frequenly asked questions about Transcrypt.

Media & presentations about Transcrypt in general

Articles, mentions, talks.

StackOverflow

StackOverflow is a handy medium to pose questions about Transcrypt. By using StackOverflow, the answer to your question can help others as well.

Python 3.7 Documentation

A good background reference, since Transcrypt covers most of the Python 3.7 language core and has exactly same syntax. However note that Transcrypt mostly uses JavaScript libraries rather than Python ones.

Numscrypt Documentation

Numscrypt is a port of a small but relevant part of Numpy to Transcrypt. To achieve speed comparable to native JavaScript numerical libraries, it only supports 1D and 2D arrays and avoids reshaping or views. To find out what is already there, read the chapter about currently available features. The quickest way to learn Numscrypt is to study the examples in its documentation.

FAQ

What overhead can I expect when using Transcrypt rather than JavaScript?

The minified JavaScript code for each of your own modules is roughly just as large as the Python source code. On top of that there's a one time overhead of 20kB for Transcrypt's core and built-ins. Should you use the JavaScript 5 to 6 translator, that adds an extra 10kB. For larger projects, the overhead becomes negligeable. A project with a Python source of say 600kB tends to result in a dowload of about equal size. Moreover Python sourcecode for a certain application tends to be smaller than handwritten JavaScript source code for the same problem, due to language constructs like list comprehensions, but also due to facilities like class based OO and multiple inheritance.

As far as speed is concerned, in most cases it is roughly equal to the speed of hand-written JavaScript. There's quite some optimization going on. A construct like i=i-1 will e.g. compile into i--. With the call caching switch on, speed will surpass the speed of straightforward hand-written JavaScript function calls. As JavaScript gradually moves to support of a richer set of data structures on the majority of browsers, Transcrypt will benefit from that by moving from emulation to directly using JavaScript equivalents. This doesn't require any changes in your source code.

I am used to interspersing all kinds of JavaScript fragments in my page. With Transcrypt what I get is a single application with possibly different entrypoints. Why is that?

In JavaScript small fragments of code cooperate (or interfere) via the global namespace. In Transcrypt you have one stateful application per page in its own private namespace. In general JavaScript is originally meant to add small pieces of active behaviour to an otherwise static webpage. With Transcrypt the perspective is different. A web page is considered a coherent, stateful client-side computer program, and the HTML and CSS merely serve to define its user interface. Since Transcrypt was designed to seamlessly cooperate with any JavaScript code, it can interact with existing pages that have all those JavaScript fragments. It can just call them or be called by them.

Why can't I use Python code between script tags?

Since Transcrypt uses precompilation on the development machine, it can be much faster and smaller than if it would use just-in-time compilation in the browser of Python source code between script tags. In the latter case compilation would take time at every page load and the compiler would have to be included in every single page that the browser requests.

Why has the choice been made to support JavaScript libraries rather than the Python standard libraries?

Transcrypt is designed to stand with both legs in the web world. A tidal wave of JavaScript libraries provides functionality that is meaningful in a browser or Node environment. They represent the mainstream and web developers need unimpeded access to them. Locking up developers in some clever all Pythonic world-in-a-world will not work, the internet is too dynamic for that. Of course quite some of the Python standard libraries would be useful in a browser, so there's no reason not to port them. A small number of them has been ported already and more will follow. Since Transcrypt is open source, you're invited to port your favorite library!

Can I write libraries in Transcrypt and distribute them in the JavaScript world?

Sure you can! Fortunately the browser-dictated prevalence of JavaScript in the internet world doesn't mean that everyone is forced to program in it. Fast, small libraries can be written in Transcrypt for any application area. And they can be used from JavaScript much like any other library. The JavaScript developers will see readable or minified JavaScript rather than Python, unless the developer chooses to include sourcemaps.

Restriction: To achieve speed, Transcrypt adds attributes to native JavaScript objects. In the rare case another library does the same thing, this may lead to conflicts, depending on load order. While such conflicts can be avoided by using identifier aliasing, this is currently not done, since it would reduce readability of the generated JavaScript.

Can I write libraries in JavaScript for Transcrypt that have their own namespace and are imported just like any other Transcrypt module?

Yes. Transcrypt supports the concept of a JavaScript-only module. If it doesn't find any Python files for a certain module, it will just load the JavaScript code of that module, which may be handwritten. In fact the whole '__builtin__' module is a JavaScript-only module. By the way don't be shy in abundantly commenting the JavaScript source of such modules, the minifier will strip them anyhow.

In the docs it says you can either use 3rd party JavaScript libraries as-is, or encapsulate them to have their own namespace and be used via Python's module import syntax. Shouldn't encapsulation always be done, since it gives modules a Pythonic interface, e.g. voiding the need for the __new__ () function?

In general: no. Completely encapsulating all JavaScript libraries you might ever use is undoable, since they typically will contain many functions you'll never need, new functions being added with every release. In many cases it is wise to connect to the JavaScript world as-is.

But if there are a few libraries that you use very often, encapsulation is worthwhile. Also you could choose to create a stable API in the flurry of versions of a library, encapsulating only a subset of what it has to offer, probably even abstracting away the library's details to allow for flexible second sourcing.

I am using Django (or Python framework X) on the server side. Can I share code between client and server?

Certainly. To be shareable in this way, the sourcecode of a module has to adhere to the subset of language facilities that CPython and Transcrypt have in common. And its directory has to be in the search path of both your CPython and Transcrypt code.

I am using Node.js. Can I share Python code between client and server?

Since Transcrypt compiles Python to plain JavaScript, you can use it on both sides of the line. Of course you can only use facilities that are present on the platform at hand, e.g. it makes no sense to manipulate a DOM tree at the server side of a Node.js application. But anything you can do in JavaScript on client and server you can do from Python source code in Transcrypt.

I am using React.js. Can I embed JSX source code in my Python files?

Yes, you can. By using the xtrans pragma you can pipe embedded code to any external translator. The result will be inserted in the generated JavaScript. Using an external JSX translator is just one possibility.

How can I use static typing?

Static typing support comes completely integrated in the Transcrypt distribution. All you have to do is add type annotations in your code at strategic places, e.g. API's and compile with the -ds / --dstat command line switch.

What should I do if I need support?

The first place to go is probably StackOverflow. Tag your question with [Transcrypt] and [Python] to maximize the likelyhood of a useful answer. Commercial support is available on demand, e.g. via GEATEC engineering.

I'd like to offer commercial support for Transcrypt. Are there any policies with regard to this?

You're encouraged to do so! The only policy is that you make clear that you're in no way commercially affiliated with Transcrypt, its developers or their companies. You can drop us a mail if you like, so that we may refer people to you, on demand or via the website.

Is there a policy in place with regard to donations?

Transcrypt is and will remain free, and there's absolutely no obligation to donate. However if you're using it a great deal professionally and want to facilitate further development, donations are welcome.

What's the position of Numscrypt with respect to Numpy?

Numscrypt is a pre-release port of a tiny part of Numpy to JavaScript and, with that, to the browser environment. On one hand, Numscrypt will never even remotely be a match for Numpy and the whole ecosystem that has grown around it, especially since it is confined to interpreted execution in a browser, rather than compiled (C++) execution on a Linux cluster. If you need high-volume computing, stick to CPython, Numpy, Scipy and all that comes with it.

If you need limited computing functionality in the browser, using a much nicer notation than any JavaScript numerical library could ever provide, Numscrypt may already be a good choice depending on the problem at hand. Its storage model is much simpler than Numpy's, avoiding things like reshaping, views and unlimited dimensionality, which would require time consuming index calculations. In that sense it certainly makes the best of the limitations that apply in a browser. It can compete with numerical libraries directly written in JavaScript with regard to speed an compactness, but not yet with regard to completeness.

Besides serving as a routine low volume computational tool, Numscrypt can be used in education, enabling browser based demonstrations in the area of linear algebra and signal processing. It's also suitable as a platform to experiment with e.g. GPGPU or ASM.js.

Currently Numscrypt supports basic real and complex matrix and vector operations using slice notation and operator overloading. It also features matrix inversion, eigenvalue / eigenvector decomposition and the 1D and 2D forward and inverse Fourier Transform. What's already there is solid enough to serve as a basis for further growth.

Media & presentations about Transcrypt in general