Sua primeira aplicação CherryPy

A aplicação padrão "Hello world!" fica com menos de 10 linhas de código quando escrita usando CherryPy.

import cherrypy

class HelloWorld:
    def index(self):
        return "Hello world!"
    index.exposed = True

cherrypy.root = HelloWorld()
cherrypy.server.start()

Assumiremos que você já tem CherryPy e Python instalados. Copie esse arquivo e salve-o localmente como hello.py; depois, inicie um prompt de comando:

python hello.py

Aponte seu navegador favorito para http://localhost:8080 e você deverá ver "Hello world!" na tela.

Como funciona?

Vamos dar uma olahda no hello.py:

• A expressão import cherrypy importa o módulo principal do CherryPy. Isso é tudo o que você precisa para ter o CherryPy na sua aplicação.
• Nós declaramos uma classe chamada HelloWorld. Uma instância dessa classe é o objeto que seja publicado pelo CherryPy. Ele contém um único método chamado "index", o qual será chamado quando a URL base do site for requisitada (por exemplo, http:/localhost/). Esse método retorna o conteúdo da página web; nesse caso, a string "Hello World!".
• A expressão index.exposed = True é um passo necessário para dizer ao CherrPy que o método index() deve ser exposto. Somente métodos expostos podem responder uma requisição. Esse recurso permite que o programador selecione que métodos de um objeto estarão acessíveis via web; métodos não-expostos não podem ser acessados.
• A expressão cherrypy.root = HelloWorld() publica uma instância da classe "HelloWorld".
• A chamada cherrypy.server.start() inicia o servidor web embutido. Esse servidor é executado até ser interrompido explicitamente, usando Ctrl+C ou via sinais (um simples "kill" em um Unix pode fazê-lo). Também é possível implementar o desligamento do servidor dentro da aplicação, mas isso está fora do escopo desse tutorial.

Quando a aplicação é executada, o servidor CherryPy é iniciado com a configuração padrão. Ele vai escutar em localhost na porta 8080. Esses padrões podem ser sobrescritos por um arquivo de configuração (mais sobre esse assunto depois).

Por fim, o servidor web recebe uma requisição para a URL http://localhost:8080. Ele procura pelo método que melhor se encaixa à requisição, iniciando por cherrypy.root (que é a instância de HelloWorld). Nesse caso particular, a base do site é automaticamente mapeada para o método index() (de maneira similar ao index.html que é a página inicial para servidores web convencionais). A classe "HelloWorld" define o método index() e o expõe. CherryPy chama cherrypy.root.index() e o resultado da chamada é enviado de volta ao navegador como conteúdo da página inicial do website. Todo o trabalho é feito automaticamente; o programador só precisa fornecer o conteúdo desejado como valor de retorno do método index().

Conceitos

Publicando objetos

Qualquer objeto que é inserido em cherrypy.root é publicado. Isso significa que o objeto se torna acessível pela rotina interna de mapeamento URL-objeto. Porém, isso não significa que o objeto em si é diretamente acessível via Web. Para isso acontecer, o objeto deve ser exposto.

Expondo objetos

CherryPy mapeia requisições para URLs para objetos e chama o método apropriado automaticamente. Esse método que pode ser chamado como resultado de requisições externas é dito que é exposto.

Objetos são expostos no CherryPy setando o atributo "exposed". Isso pode ser feito diretamente no objeto: objeto.exposed = True. Métodos podem ser expostos também usando um decorator especial:

import cherrypy

class HelloWorld:
    @exposed
    def index(self):
        return "Hello world!"

cherrypy.root = HelloWorld()
cherrypy.server.start()

Por quê essa distinção??

A distinção entre objetos publicados e expostos pode parecer inútil à primeira vista. Por definição, todos os objetos são automaticamente publicados, então por quê nós temos que nos preocupar com objetos não-expostos?

A resposta é que, apesar de que somente objetos expostos possam ser acessados como resultado de uma requisição externa, existem algumas situações onde requisições podem ser re-mapeadas para qualquer objeto publicado, incluindo objetos não-expostos. Isso é um recurso avançado que vamos explicar depois. Agora tudo o que precisamos é entender os conceitos básicos.

Encontrado o objeto certo

Para o usuário, uma aplicação web é exatamente como um website com arquivos estáticos. O usuário digita (ou clica) em uma URL e chega à página desejada. Um servidor web convencional usa a URL para carregar um arquivo estático do sistema de arquivos. Por outro lado, o servidor de aplicações web não somente serve conteúdo de arquivos estáticos; ele também pode mapear a URL que ele recebe em algum objeto e chamá-lo. O resultado então é enviado de volta para o navegador do usuário, onde é renderizado como uma página web. O resultado é uma aplicação web dinâmica: para cada URL, um objeto única pode ser chamado e executado.

A chave para entender como executar uma nova aplicação web é entenendo como esse mapeamento ocorre. CherryPy usa um procedimento de mapeamento bastante singular. A base do site é o objeto cherrypy.root. Quando o objeto recebe uma URL, ele a separa pelos componentes do caminho (path), e começa a procurar dentro das classes até encontra o objeto que é mais adequado para aquela URL particularmente. Para cada componente ele tenta encontrar o objeto como mesmo nome, iniciando por cherrypy.root, e vai "descendo" para cada componente que encontra até não encontrar mais nada. Um exemplo explica melhor:

cherrypy.root.onepage = OnePage()
cherrypy.root.otherpage = OtherPage()

No exemplo acima, a URL http://localhost/onepage vai apontar para o primeiro objeto e a URL http://localhost/otherpage vai apontar para o segundo. Como é de se esperar, essa busca é feita automaticamente. Mas pode ser feito ainda mais com o mapeamento:

cherrypy.root.some = Page()
cherrypy.root.some.page = Page()

Nesse exemplo, a URL http://localhost/some/page vai ser mapeada para o objeto cherrypy.root.some.page. Se esse objeto está exposto (ou seu método index() está), ele vai ser chamado para aquela URL.

O método index()

O método index() tem uma regra especial no CherryPy. Como um arquivo index.html, ele é a página padrão para qualquer nó interno na árvore de objetos. O método index() é o único método que não suporta parâmetros posicionais.

O método index() só é chamado se a URL inteira é válida. Se a URL é parcialmente válida (em outras palavras, se o CherryPy não conseguiu encontrar um objeto correspondente à um componente da URL) o método não será chamado.